Running Cozy inside Docker¶
Cozycloud publish the
cozy/cozy-stack docker production image to run the
cozy-stack inside a docker container. It comes with everything bundled and
- asynchronous konnector and services execution
- preconfigured PDF and SVG thumbnail generation
- Mail relay
Cozycloud also publish a docker-compose onfiguration to automatically setup a whole Cozy hosting infrastructure inside docker for selfhosting purposes with a CouchDB database as well as a frontend reverse proxy with on-demand TLS (automatic TLS certificate issuance).
This guide will help you selfhost your Cozy inside docker with docker-compose.
First you need a working docker installation with compose plugin.
Plense refer to official Docker installation guide for detailed instructions.
If you don’t work as root, add your unpriviledged user to the
Refer to docker documentation on
how to manage docker as a non-root user
docker-compose comes in two flavor. The first, v1, is a serapate python
docker-compose, the second, v2, is a plugin to the
docker command called with
docker compose (with a space instead of a
In this documentation, we will use the newer
docker compose version.
If you still use the old separate executable, remplace all
You also need a domain name or a subdomain under which all your cozy instances
will reside. For example, if you want all your cozy instances under the
domain.example domain. Configure your domain to point to your server in your
@ IN A <your server IP> * IN A <your server IP>
If you prefer tu use a subdomain of your main domain, in case you use it for
anything else, simply create DNS entries pointing to your server for that
subdomain. For exmaple if you want all your instances to be located under
cozy subdomain of your
domain.example domain, you need to add a
wildcard dns entry to your server like this:
cozy IN A <your server IP> *.cozy IN A <your server IP>
Clone cozy-stack docker-compose repository¶
sudo git clone https://github.com/cozy/cozy-stack-compose.git /opt/cozy sudo chown -R `whoami`: /opt/cozy
Copy the configuration file
env.template file to
cp env.example .env
and edit this
.env file to configure your environment.
You should at least edit the following variables:
DOMAIN: The domain under which all your instances will be served. In our example, it’s
cozy.domain.exampleif you use a subdomain.
ACME_EMAIL: The email under which you want the TLS certificates to be issued with Let’s Encrypt
COUCHDB_PASSWORD: Generate and define a strong password for cozy-stack to connect to CouchDB
COZY_ADMIN_PASSPHRASE: The cozy-stack administrative password. Generate and define a strong admin password. If unset a random password will be chosen and shown in stack logs. If you want cozy-stack cli to ask for the password everytime, you can undefine this variable and restart container after the first run
Starting the environment¶
You can then start with
docker-compose up -d
cozy-stack commands inside the docker container, you can use the
cozy-stack.sh script that executes the
cozy-stack command inside
the docker container with provided arguments.
You can execute any
cozy-stack command by simply replacing
To create your first instance:
cd /opt/cozy ./cozy-stack.sh instances add \ --apps home,banks,contacts,drive,notes,passwords,photos,settings,store \ --email "email@example.com" \ --locale fr \ --tz "Europe/Paris" \ --passphrase YourStrongP@ssw0rd \ myinstance.domain.example
And then direct your browser to https://myinstance.domain.example.
The first time you access an application it will take a handful of seconds for the Caddy reverse proxy to automatically generate the TLS certificate.
All data will be stored in a
volumes subdirectory. You can backup them.
You can list running containers with their state with
docker compose ps
In case something gets wrong, you can access logs from docker compose.
docker compose logs stack
Caddy reverse proxy
docker compose logs caddy
docker compose logs couchdb
docker compose down
To upgrade to latest version, you need to stop the whole environment, pull the new images and restart it. Carefully plan the upgrade as it will lead to service interruption during the upgrade.
docker compose down
docker compose pull
docker compose up -d