Skip to content

Commit 76a3853

Browse files
sblaisotsblaisot
committed
docs: Add doc for selfhosting using docker compose
1 parent ed91189 commit 76a3853

File tree

3 files changed

+235
-33
lines changed

3 files changed

+235
-33
lines changed

‎mkdocs.yml.tpl

+19-17
Original file line numberDiff line numberDiff line change
@@ -31,23 +31,25 @@ nav:
3131
- Advanced: tutorials/data/advanced.md
3232
- Self-Hosting:
3333
- Introduction: tutorials/selfhosting/index.md
34-
- Requirements:
35-
- What you need: tutorials/selfhosting/requirements/index.md
36-
- Installing CouchDB: tutorials/selfhosting/requirements/couchdb.md
37-
- Installing NodeJS: tutorials/selfhosting/requirements/nodejs.md
38-
- Installing cozy-stack:
39-
- Introduction: tutorials/selfhosting/install/index.md
40-
- From precompiled package: tutorials/selfhosting/install/package.md
41-
- From sources: tutorials/selfhosting/install/sources.md
42-
- Finalize installation:
43-
- Nginx and certificates: tutorials/selfhosting/finalize/nginx.md
44-
- Create first instance: tutorials/selfhosting/finalize/create_instance.md
45-
- Administration:
46-
- Index: tutorials/selfhosting/administration/index.md
47-
- Create more instances: tutorials/selfhosting/administration/more_instances.md
48-
- Upgrade cozy-stack: tutorials/selfhosting/administration/upgrade.md
49-
- Configure mail sending: tutorials/selfhosting//administration/mail.md
50-
- Online edition of office documents: tutorials/selfhosting/administration/office.md
34+
- Running inside Docker: tutorials/selfhosting/docker/index.md
35+
- Traditional installation:
36+
- Requirements:
37+
- What you need: tutorials/selfhosting/requirements/index.md
38+
- Installing CouchDB: tutorials/selfhosting/requirements/couchdb.md
39+
- Installing NodeJS: tutorials/selfhosting/requirements/nodejs.md
40+
- Installing cozy-stack:
41+
- Introduction: tutorials/selfhosting/install/index.md
42+
- From precompiled package: tutorials/selfhosting/install/package.md
43+
- From sources: tutorials/selfhosting/install/sources.md
44+
- Finalize installation:
45+
- Nginx and certificates: tutorials/selfhosting/finalize/nginx.md
46+
- Create first instance: tutorials/selfhosting/finalize/create_instance.md
47+
- Administration:
48+
- Index: tutorials/selfhosting/administration/index.md
49+
- Create more instances: tutorials/selfhosting/administration/more_instances.md
50+
- Upgrade cozy-stack: tutorials/selfhosting/administration/upgrade.md
51+
- Configure mail sending: tutorials/selfhosting//administration/mail.md
52+
- Online edition of office documents: tutorials/selfhosting/administration/office.md
5153
- How-to:
5254
- Dev:
5355
- Run an App in a Cozy using Docker: howTos/dev/runCozyDocker.md

‎src/tutorials/selfhosting/docker/index.md

+197
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
# Running Cozy inside Docker
2+
3+
## Introduction
4+
5+
Cozycloud publish the `cozy/cozy-stack` docker production image to run the
6+
`cozy-stack` inside a docker container. It comes with everything bundled and
7+
preconfigured:
8+
9+
- `cozy-stack` backend server
10+
- asynchronous konnector and services execution
11+
- preconfigured PDF and SVG thumbnail generation
12+
- Mail relay
13+
- ...
14+
15+
Cozycloud also publish a docker-compose onfiguration to automatically
16+
setup a whole Cozy hosting infrastructure inside docker for selfhosting
17+
purposes with a CouchDB database as well as a frontend reverse proxy with
18+
on-demand TLS (automatic TLS certificate issuance).
19+
20+
This guide will help you selfhost your Cozy inside docker with docker-compose.
21+
22+
## Requirements
23+
24+
First you need a working docker installation with compose plugin.
25+
26+
Plense refer to official [Docker installation guide](https://docs.docker.com/engine/install/) for detailed instructions.
27+
28+
If you don't work as root, add your unpriviledged user to the `docker` group.
29+
Refer to docker documentation on
30+
[how to manage docker as a non-root user](https://docs.docker.com/engine/install/linux-postinstall/#manage-docker-as-a-non-root-user)
31+
32+
!!! note
33+
34+
docker-compose comes in two flavor. The first, v1, is a serapate python
35+
executable called `docker-compose`, the second, v2, is a plugin to the
36+
`docker` command called with `docker compose` (with a space instead of a
37+
dash between `docker` and `compose`).
38+
39+
In this documentation, we will use the newer `docker compose` version.
40+
If you still use the old separate executable, remplace all `docker compose`
41+
occurences with `docker-compose`
42+
43+
You also need a domain name or a subdomain under which all your cozy instances
44+
will reside. For example, if you want all your cozy instances under the
45+
`domain.example` domain. Configure your domain to point to your server in your
46+
domain's DNS:
47+
48+
```dns
49+
@ IN A <your server IP>
50+
* IN A <your server IP>
51+
```
52+
53+
If you prefer tu use a subdomain of your main domain, in case you use it for
54+
anything else, simply create DNS entries pointing to your server for that
55+
subdomain. For exmaple if you want all your instances to be located under
56+
the `cozy` subdomain of your `domain.example` domain, you need to add a
57+
wildcard dns entry to your server like this:
58+
59+
```dns
60+
cozy IN A <your server IP>
61+
*.cozy IN A <your server IP>
62+
```
63+
64+
## Clone cozy-stack docker-compose repository
65+
66+
```bash
67+
sudo git clone https://github.com/cozy/cozy-stack-compose.git /opt/cozy
68+
sudo chown -R `whoami`: /opt/cozy
69+
```
70+
71+
## Configuration
72+
73+
Copy the configuration file `env.template` file to `.env`
74+
75+
```bash
76+
cd /opt/cozy
77+
cp env.example .env
78+
```
79+
80+
and edit this `.env` file to configure your environment.
81+
82+
You should at least edit the following variables:
83+
84+
- `DOMAIN`: The domain under which all your instances will be served.
85+
In our example, it's `domain.example` or `cozy.domain.example` if you use
86+
a subdomain.
87+
- `ACME_EMAIL`: The email under which you want the TLS certificates to be
88+
issued with Let's Encrypt
89+
- `COUCHDB_PASSWORD`: Generate and define a strong password for cozy-stack to
90+
connect to CouchDB
91+
- `COZY_ADMIN_PASSPHRASE`: The cozy-stack administrative password. Generate
92+
and define a strong admin password. If unset a random password will be chosen
93+
and shown in stack logs. If you want cozy-stack cli to ask for the password
94+
everytime, you can undefine this variable and restart container after the
95+
first run
96+
97+
## Starting the environment
98+
99+
You can then start with
100+
101+
```bash
102+
cd /opt/cozy
103+
docker-compose up -d
104+
```
105+
106+
## Create instance
107+
108+
To execute `cozy-stack` commands inside the docker container, you can use the
109+
provided `cozy-stack.sh` script that executes the `cozy-stack` command inside
110+
the docker container with provided arguments.
111+
112+
You can execute any `cozy-stack` command by simply replacing `cozy-stack` with
113+
`./cozy-stack.sh`
114+
115+
For example:
116+
117+
```bash
118+
cd /opt/cozy
119+
./cozy-stack.sh status
120+
```
121+
122+
To create your first instance:
123+
124+
```bash
125+
cd /opt/cozy
126+
./cozy-stack.sh instances add \
127+
--apps home,banks,contacts,drive,notes,passwords,photos,settings,store \
128+
--email "[email protected]" \
129+
--locale fr \
130+
--tz "Europe/Paris" \
131+
--passphrase YourStrongP@ssw0rd \
132+
myinstance.domain.example
133+
```
134+
135+
And then direct your browser to <https://myinstance.domain.example>.
136+
137+
The first time you access an application it will take a handful of seconds for
138+
the Caddy reverse proxy to automatically generate the TLS certificate.
139+
140+
All data will be stored in a `volumes` subdirectory. You can backup them.
141+
142+
## Going further
143+
144+
### Debugging
145+
146+
You can list running containers with their state with
147+
148+
```bash
149+
cd /opt/cozy
150+
docker compose ps
151+
```
152+
153+
In case something gets wrong, you can access logs from docker compose.
154+
155+
**cozy-stack logs**
156+
157+
```bash
158+
cd /opt/cozy
159+
docker compose logs stack
160+
```
161+
162+
**Caddy reverse proxy**
163+
164+
```bash
165+
cd /opt/cozy
166+
docker compose logs caddy
167+
```
168+
169+
**CouchDB logs**
170+
171+
```bash
172+
cd /opt/cozy
173+
docker compose logs couchdb
174+
```
175+
176+
### Stopping environment
177+
178+
Simply run
179+
180+
```bash
181+
cd /opt/cozy
182+
docker compose down
183+
```
184+
185+
### Upgrading
186+
187+
To upgrade to latest version, you need to stop the whole environment, pull the
188+
new images and restart it. Carefully plan the upgrade as it will lead to
189+
service interruption during the upgrade.
190+
191+
```bash
192+
cd /opt/cozy
193+
docker compose down
194+
git pull
195+
docker compose pull
196+
docker compose up -d
197+
```

‎src/tutorials/selfhosting/index.md

+19-16
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ We are commited to protect your data and respect your privacy and are convinced
88
The cozycloud source code is publicly available to be audited and you can decide to host it yourself or ask someone else you trust to host your cozy.
99

1010
This documentation explains how to self host your cozy instance on your own server.
11+
You can choose either a traditioinal install on your server or to host Cozy in a docker environment.
1112

1213
Cozycloud provides precompiled packages for the last two major versions of Debian and Ubuntu LTS on the amd64 architecture, as well as installation instructions from source code for other architectures and operating systems.
1314

@@ -25,22 +26,24 @@ documentation so that we can fix it.
2526

2627
<!--lint disable list-item-bullet-indent-->
2728

28-
- Requirements
29-
- [What you need](./requirements/index.md)
30-
- [CouchDB](./requirements/couchdb.md)
31-
- [NodeJS](./requirements/nodejs.md)
32-
- Installing cozy-stack
33-
- [Introduction](./install/index.md)
34-
- [Installing from precompiled package](./install/package.md)
35-
- [Installing from source](./install/sources.md)
36-
- Finalize installation
37-
- [Nginx and certificates](./finalize/nginx.md)
38-
- [Create your first instance](./finalize/create_instance.md)
39-
- [Administration](./administration/index.md)
40-
- [Create more instances](./administration/more_instances.md)
41-
- [Upgrade cozy-stack](./administration/upgrade.md)
42-
- [Configure mail sending](./administration/mail.md)
43-
- [Online edition of office documents](./administration/office.md)
29+
- [Self hosting with docker](./docker/index.md)
30+
- Traditional installation
31+
- Requirements
32+
- [What you need](./requirements/index.md)
33+
- [CouchDB](./requirements/couchdb.md)
34+
- [NodeJS](./requirements/nodejs.md)
35+
- Installing cozy-stack
36+
- [Introduction](./install/index.md)
37+
- [Installing from precompiled package](./install/package.md)
38+
- [Installing from source](./install/sources.md)
39+
- Finalize installation
40+
- [Nginx and certificates](./finalize/nginx.md)
41+
- [Create your first instance](./finalize/create_instance.md)
42+
- [Administration](./administration/index.md)
43+
- [Create more instances](./administration/more_instances.md)
44+
- [Upgrade cozy-stack](./administration/upgrade.md)
45+
- [Configure mail sending](./administration/mail.md)
46+
- [Online edition of office documents](./administration/office.md)
4447

4548
<!--lint enable list-item-bullet-indent-->
4649

0 commit comments

Comments
 (0)