1
0
mirror of https://github.com/LaCasemate/fab-manager.git synced 2024-12-10 21:24:20 +01:00
fab-manager/docker/README.md

370 lines
12 KiB
Markdown
Raw Normal View History

2017-07-20 16:48:34 +02:00
# Install Fabmanager app in production with Docker
2016-03-23 18:39:41 +01:00
2017-07-20 19:54:37 +02:00
This README tries to describe all the steps to put a fabmanager app into production on a server, based on a solution using Docker and Docker-compose.
We recommend DigitalOcean, but these steps will work on any Docker-compatible cloud provider or local server.
2017-07-20 16:48:34 +02:00
In order to make it work, please use the same directories structure as described in this guide in your fabmanager app folder.
2017-07-20 19:54:37 +02:00
You will need to be root through the rest of the setup.
2016-03-23 18:39:41 +01:00
2017-07-20 17:14:02 +02:00
##### Table of contents
2017-07-20 17:18:19 +02:00
1. [Preliminary steps](#preliminary-steps)<br/>
2017-12-13 17:51:44 +01:00
1.1. Setup the server<br/>
1.2. Setup the domain name<br/>
1.3. Connect through SSH<br/>
1.4. Prepare the server<br/>
2017-12-14 14:33:49 +01:00
1.5. Retrieve the initial configuration files<br/>
1.6. Setup folders and env file<br/>
1.7. Setup nginx configuration<br/>
1.8. SSL certificate with LetsEncrypt<br/>
1.9. Requirements
2017-12-13 17:51:44 +01:00
2. [Install Fab-manager](#install-fabmanager)<br/>
2017-07-21 09:27:29 +02:00
2.1. Add docker-compose.yml file<br/>
2.2. pull images<br/>
2.3. setup database<br/>
2.4. build assets<br/>
2.5. prepare Elasticsearch (search engine)<br/>
2017-12-14 14:33:49 +01:00
2.6. start all services<br/>
2.7. Generate SSL certificate by Let's encrypt
2017-07-20 17:14:02 +02:00
4. [Docker utils](#docker-utils)
2017-12-14 14:33:49 +01:00
5. [Update Fab-manager](#update-fabmanager)<br/>
2017-07-20 17:42:55 +02:00
5.1. Steps<br/>
5.2. Good to know
2017-07-20 17:14:02 +02:00
2017-12-13 17:51:44 +01:00
<a name="preliminary-steps"></a>
2017-07-20 17:37:03 +02:00
## Preliminary steps
2017-07-20 16:48:34 +02:00
2017-12-14 14:33:49 +01:00
<a name="setup-the-server"></a>
2017-12-13 17:51:44 +01:00
### Setup the server
There are many hosting providers on the internet, providing affordable virtual private serveurs (VPS).
Here's a non exhaustive list:
- [DigitalOcean](https://www.digitalocean.com/pricing/#droplet)
- [OVH](https://www.ovh.com/fr/vps/)
- [Amazon](https://aws.amazon.com/fr/ec2/)
- [Gandi](https://v4.gandi.net/hebergement/serveur/prix)
- [Ikoula](https://express.ikoula.com/fr/serveur-virtuel)
- [1&1](https://www.1and1.fr/serveurs-virtuels)
- [GoDaddy](https://fr.godaddy.com/hosting/vps-hosting)
- [and many others...](https://www.google.fr/search?q=vps+hosting)
2017-12-14 14:41:43 +01:00
2017-12-13 17:51:44 +01:00
Choose one, depending on your budget, on the server's location, on the uptime guarantee, etc.
You will need at least 2GB of addressable memory (RAM + swap) to install and use FabManager.
2017-07-20 19:54:37 +02:00
We recommend 4 GB RAM for larger communities.
2016-04-11 20:24:09 +02:00
On DigitalOcean, create a Droplet with One-click apps **"Docker on Ubuntu 16.04 LTS"**.
2017-12-13 17:51:44 +01:00
This way, Docker and Docker-compose are preinstalled.
Choose a datacenter and set the hostname as your domain name.
2019-03-26 14:04:45 +01:00
With other providers, choose a [supported operating system](https://github.com/sleede/fab-manager/blob/master/README.md#software-stack) and install docker on it:
2017-12-13 17:51:44 +01:00
- [Debian](https://docs.docker.com/engine/installation/linux/docker-ce/debian/)
- [Ubuntu](https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/)
2017-12-14 14:41:43 +01:00
2017-12-13 17:51:44 +01:00
Then install [Docker Compose](https://docs.docker.com/compose/install/)
### Setup the domain name
2016-04-11 20:24:09 +02:00
2017-12-13 17:51:44 +01:00
There are many domain name registrars on the internet, you may choose one that fit your needs.
You can find an exhaustive list [on the ICANN website](https://www.icann.org/registrar-reports/accredited-list.html)
1. Once done, buy a domain name on it
2. Replace the IP address of the domain with the IP address of your VPS (This is a DNS record type A)
2017-07-20 16:48:34 +02:00
3. **Do not** try to access your domain name right away, DNS are not aware of the change yet so **WAIT** and be patient.
2016-04-11 20:24:09 +02:00
2017-12-13 17:51:44 +01:00
### Connect through SSH
2016-04-11 20:24:09 +02:00
2017-07-20 19:54:37 +02:00
You can already connect to the server with this command: `ssh root@server-ip`. When DNS propagation will be done, you will be able to
connect to the server with `ssh root@your-domain-name`.
2016-03-23 18:39:41 +01:00
2017-12-13 17:51:44 +01:00
### Prepare the server
Before installing fab-manager, we recommend you to:
- Upgrade your system
- Setup the server timezone
- Add at least 2GB of swap memory
2017-12-14 14:33:49 +01:00
- Protect your SSH connection by forcing it through a RSA key
2016-04-11 20:24:09 +02:00
2017-12-14 14:33:49 +01:00
You can run the following script as root to easily perform all these operations:
2016-04-11 20:24:09 +02:00
2016-03-23 18:39:41 +01:00
```bash
2017-12-14 14:33:49 +01:00
\curl -sSL prepare-vps.sleede.com | bash
2016-03-23 18:39:41 +01:00
```
2017-12-14 14:33:49 +01:00
<a name="retrieve-config-files"></a>
### Retrieve the initial configuration files
```bash
2019-03-26 14:04:45 +01:00
\curl -sSL https://raw.githubusercontent.com/sleede/fab-manager/master/docker/setup.sh | bash
2019-05-29 16:51:02 +02:00
# OR, if you don't want to install fab-manager in /apps/fabmanager, use:
\curl -sSL https://raw.githubusercontent.com/sleede/fab-manager/master/docker/setup.sh | bash -s "/my/custom/path"
2017-12-14 14:33:49 +01:00
```
2016-03-23 18:39:41 +01:00
2017-12-13 17:51:44 +01:00
### Setup folders and env file
2016-03-23 18:39:41 +01:00
2017-12-14 14:33:49 +01:00
Create the config folder, copy the environnement variables configuration file and edit it:
2016-04-11 20:24:09 +02:00
```bash
2017-07-20 19:54:37 +02:00
mkdir -p /apps/fabmanager/config
2017-12-28 19:25:05 +01:00
cd /apps/fabmanager
cp example/env.example config/env
2017-12-14 14:33:49 +01:00
vi config/env
# or use your favorite text editor instead of vi (nano, ne...)
2016-04-11 20:24:09 +02:00
```
2017-12-14 14:33:49 +01:00
You need to carefully configure each variable before starting fab-manager.
Please refer to the [environment configuration documentation](../doc/environment.md) for explanations about those variables.
2016-04-11 20:24:09 +02:00
2017-07-20 19:54:37 +02:00
2017-12-14 14:33:49 +01:00
### Setup nginx configuration
2016-04-11 20:24:09 +02:00
2017-12-14 14:33:49 +01:00
Create the nginx folder, copy the example configuration file and edit it:
2016-04-11 20:24:09 +02:00
```bash
2017-07-20 19:54:37 +02:00
mkdir -p /apps/fabmanager/config/nginx
2017-12-14 14:33:49 +01:00
# whether you want you fab-manager to use SSL encryption or not, you should copy one of the following file
### with SSL ###
cp example/nginx_with_ssl.conf.example config/nginx/fabmanager.conf
### OR without SSL ###
cp example/nginx.conf.example config/nginx/fabmanager.conf
vi config/nginx/fabmanager.conf
# or use your favorite text editor instead of vi (nano, ne...)
2016-04-11 20:24:09 +02:00
```
2016-03-23 18:39:41 +01:00
2017-12-14 14:33:49 +01:00
Customize the following values:
2017-07-20 19:54:37 +02:00
* Replace **MAIN_DOMAIN** (example: fab-manager.com).
* Replace **URL_WITH_PROTOCOL_HTTPS** (example: https://www.fab-manager.com).
* Replace **ANOTHER_URL_1**, **ANOTHER_URL_2** (example: .fab-manager.fr)
2017-07-20 17:37:03 +02:00
### SSL certificate with LetsEncrypt
2017-07-20 17:14:02 +02:00
2017-07-20 17:37:03 +02:00
**FOLLOW THOSE INSTRUCTIONS ONLY IF YOU WANT TO USE SSL**.
2017-12-14 14:41:43 +01:00
2017-12-14 14:33:49 +01:00
If you have chosen the SSL configuration at the previous point, you must follow these instructions to make it work.
2017-07-20 16:48:34 +02:00
Let's Encrypt is a new Certificate Authority that is free, automated, and open.
Lets Encrypt certificates expire after 90 days, so automation of renewing your certificates is important.
2017-07-20 16:48:34 +02:00
Here is the setup for a systemd timer and service to renew the certificates and reboot the app Docker container:
2017-12-14 14:33:49 +01:00
Generate the dhparam.pem file
```bash
2017-07-20 19:54:37 +02:00
mkdir -p /apps/fabmanager/config/nginx/ssl
2017-12-14 14:33:49 +01:00
cd /apps/fabmanager/config/nginx/ssl
openssl dhparam -out dhparam.pem 4096
```
2017-12-14 14:33:49 +01:00
Copy the initial configuration file and customize it
```bash
2017-12-14 14:33:49 +01:00
cd /apps/fabmanager/
mkdir -p letsencrypt/config/
mkdir -p letsencrypt/etc/webrootauth
cp example/webroot.ini.example /apps/fabmanager/letsencrypt/config/webroot.ini
vi letsencrypt/config/webroot.ini
# or use your favorite text editor instead of vi (nano, ne...)
```
Run `docker pull quay.io/letsencrypt/letsencrypt:latest`
2017-07-20 16:48:34 +02:00
Create file (with sudo) /etc/systemd/system/letsencrypt.service and paste the following configuration into it:
2017-12-14 14:41:43 +01:00
```systemd
[Unit]
Description=letsencrypt cert update oneshot
Requires=docker.service
[Service]
Type=oneshot
2017-07-20 19:54:37 +02:00
ExecStart=/usr/bin/docker run --rm --name letsencrypt -v "/apps/fabmanager/log:/var/log/letsencrypt" -v "/apps/fabmanager/letsencrypt/etc:/etc/letsencrypt" -v "/apps/fabmanager/letsencrypt/config:/letsencrypt-config" quay.io/letsencrypt/letsencrypt:latest -c "/letsencrypt-config/webroot.ini" certonly
2016-11-30 21:48:46 +01:00
ExecStartPost=-/usr/bin/docker restart fabmanager_nginx_1
```
2017-07-20 16:48:34 +02:00
Create file (with sudo) /etc/systemd/system/letsencrypt.timer and paste the following configuration into it:
2017-12-14 14:41:43 +01:00
```systemd
[Unit]
Description=letsencrypt oneshot timer
Requires=docker.service
[Timer]
OnCalendar=*-*-1 06:00:00
Persistent=true
Unit=letsencrypt.service
2016-11-30 21:48:46 +01:00
[Install]
WantedBy=timers.target
```
2017-12-14 14:33:49 +01:00
That's all for the moment. Keep on with the installation, we'll complete that part after deployment in the [Generate SSL certificate by Let's encrypt](#generate-ssl-cert-letsencrypt).
2016-03-23 18:39:41 +01:00
2017-07-20 19:54:37 +02:00
### Requirements
Verify that Docker and Docker-composer are installed :
(This is normally the case if you used a pre-configured image.)
2016-03-23 18:39:41 +01:00
```bash
2017-07-20 19:54:37 +02:00
docker info
docker-compose -v
```
2017-12-14 14:33:49 +01:00
Otherwise, follow the instructions provided in the section [Setup the server](#setup-the-server) to install.
2017-07-20 19:54:37 +02:00
2017-12-14 14:33:49 +01:00
<a name="install-fabmanager"></a>
2017-07-20 19:54:37 +02:00
## Install Fabmanager
### Add docker-compose.yml file
2017-12-14 14:33:49 +01:00
You should already have a `docker-compose.yml` file in your app folder `/apps/fabmanager`.
Otherwise, see the section [Retrieve the initial configuration files](#retrieve-config-files) to get it.
2017-07-20 19:54:37 +02:00
The docker-compose commands must be launched from the folder `/apps/fabmanager`.
2016-03-23 18:39:41 +01:00
2017-07-20 17:37:03 +02:00
### pull images
2016-03-23 18:39:41 +01:00
```bash
2017-07-20 16:48:34 +02:00
docker-compose pull
2016-03-23 18:39:41 +01:00
```
2017-07-20 17:37:03 +02:00
### setup database
2016-03-23 18:39:41 +01:00
```bash
2017-07-20 16:48:34 +02:00
docker-compose run --rm fabmanager bundle exec rake db:create # create the database
docker-compose run --rm fabmanager bundle exec rake db:migrate # run all the migrations
2017-11-15 10:20:23 +01:00
# replace xxx with your default admin email/password
docker-compose run --rm -e ADMIN_EMAIL=xxx -e ADMIN_PASSWORD=xxx fabmanager bundle exec rake db:seed # seed the database
2016-03-23 18:39:41 +01:00
```
2017-07-20 17:37:03 +02:00
### build assets
2016-03-23 18:39:41 +01:00
2017-07-20 16:48:34 +02:00
`docker-compose run --rm fabmanager bundle exec rake assets:precompile`
2016-03-23 18:39:41 +01:00
2017-07-20 17:37:03 +02:00
### prepare Elasticsearch (search engine)
2016-03-23 18:39:41 +01:00
2019-02-13 12:59:28 +01:00
`docker-compose run --rm fabmanager bundle exec rake fablab:es:build_stats`
2016-03-23 18:39:41 +01:00
2017-12-14 14:33:49 +01:00
### start all services
2016-03-23 18:39:41 +01:00
2017-07-20 16:48:34 +02:00
`docker-compose up -d`
2016-09-06 12:19:47 +02:00
2017-12-14 14:33:49 +01:00
<a name="generate-ssl-cert-letsencrypt"></a>
### Generate SSL certificate by Let's encrypt
2016-03-23 18:39:41 +01:00
2017-07-20 19:54:37 +02:00
**Important: app must be run on http before starting letsencrypt**
Start letsencrypt service :
```bash
sudo systemctl start letsencrypt.service
```
2017-07-20 16:48:34 +02:00
If the certificate was successfully generated then update the nginx configuration file and activate the ssl port and certificate
2017-07-20 19:54:37 +02:00
editing the file `/apps/fabmanager/config/nginx/fabmanager.conf`.
2017-07-20 16:48:34 +02:00
Remove your app container and run your app to apply the changes running the following commands:
```bash
docker-compose down
docker-compose up -d
```
Finally, if everything is ok, start letsencrypt timer to update the certificate every 1st of the month :
```bash
2016-11-30 21:48:46 +01:00
sudo systemctl enable letsencrypt.timer
sudo systemctl start letsencrypt.timer
2017-12-14 14:33:49 +01:00
# check status with
sudo systemctl list-timers
```
2017-12-14 14:33:49 +01:00
<a name="docker-utils"></a>
2017-07-20 19:54:37 +02:00
## Docker utils with docker-compose
2016-03-23 18:39:41 +01:00
2017-07-20 16:48:34 +02:00
### Restart app
2016-04-11 20:24:09 +02:00
2017-07-20 19:54:37 +02:00
`docker-compose restart fabmanager`
2016-04-11 20:24:09 +02:00
2017-07-20 16:48:34 +02:00
### Remove app
2016-04-11 20:24:09 +02:00
2017-07-20 19:54:37 +02:00
`docker-compose down fabmanager`
### Restart all containers
`docker-compose restart`
### Remove all containers
`docker-compose down`
### Start all containers
`docker-compose up -d`
2016-04-11 20:24:09 +02:00
2017-07-20 16:48:34 +02:00
### Open a bash in the app context
2016-04-11 20:24:09 +02:00
2017-07-20 19:54:37 +02:00
`docker-compose run --rm fabmanager bash`
2016-04-11 20:24:09 +02:00
2017-07-20 16:48:34 +02:00
### Show services status
2016-06-14 14:33:57 +02:00
2017-07-20 16:48:34 +02:00
`docker-compose ps`
2016-06-14 14:33:57 +02:00
2017-07-20 19:54:37 +02:00
### Restart nginx container
`docker-compose restart nginx`
### Example of command passing env variables
2017-07-20 19:54:37 +02:00
2017-12-21 11:32:13 +01:00
docker-compose run --rm -e ADMIN_EMAIL=xxx -e ADMIN_PASSWORD=xxx fabmanager bundle exec rake db:seed
2016-06-14 14:33:57 +02:00
2017-12-14 14:33:49 +01:00
<a name="update-fabmanager"></a>
## Update Fab-manager
2017-07-20 17:14:02 +02:00
*This procedure updates fabmanager to the most recent version by default.*
2017-07-20 17:14:02 +02:00
2017-07-20 17:37:03 +02:00
### Steps
2017-07-20 17:14:02 +02:00
2018-11-26 10:56:15 +01:00
When a new version is available, follow this procedure to update fab-manager app in a production environment, using docker-compose.
2019-03-26 14:04:45 +01:00
You can subscribe to [this atom feed](https://github.com/sleede/fab-manager/releases.atom) to get notified when a new release comes out.
2016-06-14 14:33:57 +02:00
2017-07-20 17:37:03 +02:00
1. go to your app folder
2016-06-14 14:33:57 +02:00
2017-07-20 19:54:37 +02:00
`cd /apps/fabmanager`
2016-06-14 14:33:57 +02:00
2017-07-20 17:37:03 +02:00
2. pull last docker images
2016-06-14 14:33:57 +02:00
`docker-compose pull`
2017-07-20 17:37:03 +02:00
3. stop the app
2016-06-14 14:33:57 +02:00
`docker-compose stop fabmanager`
2016-06-14 14:33:57 +02:00
2017-07-20 17:37:03 +02:00
4. remove old assets
2016-06-14 14:33:57 +02:00
2017-07-20 19:54:37 +02:00
`rm -Rf public/assets/`
2016-06-14 14:33:57 +02:00
2017-07-20 17:37:03 +02:00
5. compile new assets
2016-06-14 14:33:57 +02:00
`docker-compose run --rm fabmanager bundle exec rake assets:precompile`
2016-06-14 14:33:57 +02:00
2017-07-20 17:37:03 +02:00
6. run specific commands
2016-06-14 14:33:57 +02:00
**Do not forget** to check if there are commands to run for your upgrade. Those commands
2019-03-26 14:04:45 +01:00
are always specified in the [CHANGELOG](https://github.com/sleede/fab-manager/blob/master/CHANGELOG.md) and prefixed by **[TODO DEPLOY]**.
They are also present in the [releases page](https://github.com/sleede/fab-manager/releases).
Those commands execute specific tasks and have to be run by hand.
2019-03-27 17:44:19 +01:00
Using docker, you must prefix these commands with `docker-compose run --rm fabmanager bundle exec`.
You can also ignore commands only applicable to development environnement, which are prefixed by `(dev)` in the CHANGELOG.
2016-06-14 14:33:57 +02:00
2017-07-20 17:37:03 +02:00
7. restart all containers
2016-06-14 14:33:57 +02:00
```bash
docker-compose down
docker-compose up -d
```
2016-06-14 14:33:57 +02:00
2017-07-20 16:48:34 +02:00
You can check that all containers are running with `docker ps`.
2016-06-14 14:33:57 +02:00
2017-07-20 17:37:03 +02:00
### Good to know
2016-06-14 14:33:57 +02:00
2017-07-20 16:48:34 +02:00
#### Is it possible to update several versions at the same time ?
2016-06-14 14:33:57 +02:00
2017-07-20 16:48:34 +02:00
Yes, indeed. It's the default behaviour as `docker-compose pull` command will fetch the latest versions of the docker images.
2019-03-26 14:04:45 +01:00
Be sure to run all the specific commands listed in the [CHANGELOG](https://github.com/sleede/fab-manager/blob/master/CHANGELOG.md) between your actual
2017-11-15 10:20:23 +01:00
and the new version in sequential order. (Example: to update from 2.4.0 to 2.4.3, you will run the specific commands for the 2.4.1, then for the 2.4.2 and then for the 2.4.3).