Merged in DCD-639-template-modification-howto (pull request #40)

DCD-639: Add section to README about overriding the provided templates.

Approved-by: Dave Chevell <dchevell@atlassian.com>
Approved-by: Joe Xie <jxie@atlassian.com>
This commit is contained in:
Steve Smith 2019-09-04 22:46:21 +00:00
commit 696c3b1aeb

117
README.md
View File

@ -1,23 +1,27 @@
[Atlassian Confluence Server][1]
Confluence Server is where you create, organise and discuss work with your
team. Capture the knowledge that's too often lost in email inboxes and shared
network drives in Confluence where it's easy to find, use, and update. Give
every team, project, or department its own space to create the things they need,
whether it's meeting notes, product requirements, file lists, or project plans,
you can get more done in Confluence.
Learn more about Confluence Server: <https://www.atlassian.com/software/confluence>
You can find the repository for this Dockerfile at <https://hub.docker.com/r/atlassian/confluence-server>
# Contents
[TOC]
# Overview
This Docker container makes it easy to get an instance of Confluence up and
running.
# Quick Start
For the directory in the environmental variable `CONFLUENCE_HOME` that is used
to store Confluence data (amongst other things) we recommend mounting a host
directory as a [data volume][2]:
@ -25,21 +29,31 @@ directory as a [data volume][2]:
Additionally, if running Confluence in Data Center mode it is required that a
shared filesystem is mounted. The mountpoint (inside the container) can be
configured with `CONFLUENCE_SHARED_HOME`.
Start Atlassian Confluence Server:
$> docker run -v /data/your-confluence-home:/var/atlassian/application-data/confluence --name="confluence" -d -p 8090:8090 -p 8091:8091 atlassian/confluence-server
docker run -v /data/your-confluence-home:/var/atlassian/application-data/confluence --name="confluence" -d -p 8090:8090 -p 8091:8091 atlassian/confluence-server
**Success**. Confluence is now available on <http://localhost:8090>*
Please ensure your container has the necessary resources allocated to it. We
recommend 2GiB of memory allocated to accommodate the application server. See
[Supported Platforms][4] for further information.
_* Note: If you are using `docker-machine` on Mac OS X, please use `open http://$(docker-machine ip default):8090` instead._
# Configuring Confluence
This Docker image is intended to be configured from its environment; the
provided information is used to generate the application configuration files
from templates. This allows containers to be repeatably created and destroyed
on-the-fly, as required in advanced cluster configurations. Most aspects of the
deployment can be configured in this manner; the necessary environment variables
are documented below. However, if your particular deployment scenario is not
covered by these settings, it is possible to override the provided templates
with your own; see the section _Advanced Configuration_ below.
## Memory / Heap Size
If you need to override Confluence Server's default memory allocation, you can
@ -74,7 +88,7 @@ of the setup. They can be controlled via the below environment variables.
* `ATL_TOMCAT_PORT` (default: 8090)
The port for Tomcat/Confluence to listen on. Depending on your container
deployment method this port may need to be
deployment method this port may need to be
[exposed and published][docker-expose].
* `ATL_TOMCAT_SCHEME` (default: http)
@ -111,7 +125,7 @@ custom trust store, you can add them via the below environment variable
* `JVM_SUPPORT_RECOMMENDED_ARGS`
Additional JVM arguments for Confluence
Example:
docker run -e JVM_SUPPORT_RECOMMENDED_ARGS=-Djavax.net.ssl.trustStore=/var/atlassian/application-data/confluence/cacerts -v confluenceVolume:/var/atlassian/application-data/confluence --name="confluence" -d -p 8090:8090 -p 8091:8091 atlassian/confluence-server
@ -121,7 +135,7 @@ Example:
* `ATL_AUTOLOGIN_COOKIE_AGE` (default: 1209600; two weeks, in seconds)
The maximum time a user can remain logged-in with 'Remember Me'.
* `CONFLUENCE_HOME`
The confluence home directory. This may be on an mounted volume; if so it
@ -228,6 +242,43 @@ management technology, and is beyond the scope of this documentation.
The multicast address the cluster will communicate on.
## Advanced Configuration
As mentioned at the top of this section, the settings from the environment are
used to populate the application configuration on the container startup. However
in some cases you may wish to customise the settings in ways that are not
supported by the environment variables above. In this case, it is possible to
modify the base templates to add your own configuration. There are three main
ways of doing this; modify our repository to your own image, build a new image
from the existing one, or provide new templates at startup. We will briefly
outline this methods here, but in practice how you do this will depend on your
needs.
#### Building your own image
* Clone the Atlassian repository at https://bitbucket.org/atlassian-docker/docker-atlassian-confluence-server/
* Modify or replace the [Jinja](https://jinja.palletsprojects.com/) templates
under `config`; _NOTE_: The files must have the `.j2` extensions. However you
don't have to use template variables if you don't wish.
* Build the new image with e.g: `docker build --tag my-confluence-image --build-arg CONFLUENCE_VERSION=6.x.x .`
* Optionally push to a registry, and deploy.
#### Build a new image from the existing one
* Create a new `Dockerfile`, which starts with the line e.g: `FROM atlassian/confluence-server:latest`.
* Use a `COPY` line to overwrite the provided templates.
* Build, push and deploy the new image as above.
#### Overwrite the templates at runtime
There are two main ways of doing this:
* If your container is going to be long-lived, you can create it, modify the
installed templates under `/opt/atlassian/etc/`, and then run it.
* Alternatively, you can create a volume containing your alternative templates,
and mount it over the provided templates at runtime
with `--volume my-config:/opt/atlassian/etc/`.
# Shared directory and user IDs
By default the Confuence application runs as the user `confluence`, with a UID
@ -236,43 +287,43 @@ filesystem. If for some reason a different UID must be used, there are a number
of options available:
* The Docker image can be rebuilt with a different UID.
* Under Linux, the UID can be remapped using
* Under Linux, the UID can be remapped using
[user namespace remapping][8].
# Upgrade
To upgrade to a more recent version of Confluence Server you can simply stop the
`Confluence` container and start a new one based on a more recent image:
$> docker stop confluence
$> docker rm confluence
$> docker run ... (see above)
docker stop confluence
docker rm confluence
docker run ... (see above)
As your data is stored in the data volume directory on the host, it will still
be available after the upgrade.
_Note: Please make sure that you **don't** accidentally remove the `confluence`
container and its volumes using the `-v` option._
# Backup
For evaluating Confluence you can use the built-in database that will store its
files in the Confluence Server home directory. In that case it is sufficient to
create a backup archive of the directory on the host that is used as a volume
(`/data/your-confluence-home` in the example above).
Confluence's [automatic backup][9] is currently supported in the Docker
setup. You can also use the [Production Backup Strategy][10] approach if you're
using an external database.
Read more about data recovery and backups: [Site Backup and Restore][11]
# Versioning
The `latest` tag matches the most recent release of Atlassian Confluence Server.
So `atlassian/confluence-server:latest` will use the newest stable version of
Confluence Server available.
Alternatively, you can use a specific minor version of Confluence Server by
using a version number tag: `atlassian/confluence-server:6.13`. This will
install the latest `6.13.x` version that is available.
@ -283,7 +334,7 @@ supported for use in production).
For example, `atlassian/confluence-server:6.13-ubuntu-18.04-adoptopenjdk8` will
install the latest 6.13.x version with AdoptOpenJDK 8.
# Support
These Confluence Docker images are presented as a technical preview, and not