From 6ba880275fc403bf89b57272c1e6efba47ccf3a3 Mon Sep 17 00:00:00 2001 From: Cyril Date: Thu, 20 Jul 2017 19:54:37 +0200 Subject: [PATCH] Update README.md --- docker/README.md | 238 +++++++++++++++++++++++++---------------------- 1 file changed, 127 insertions(+), 111 deletions(-) diff --git a/docker/README.md b/docker/README.md index c174caa61..97bbcec4c 100644 --- a/docker/README.md +++ b/docker/README.md @@ -1,122 +1,105 @@ # Install Fabmanager app in production with Docker -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 DigitalOcean. +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. + In order to make it work, please use the same directories structure as described in this guide in your fabmanager app folder. +You will need to be root through the rest of the setup. ##### Table of contents 1. [Preliminary steps](#preliminary-steps)
-1.1. docker/env file
-1.2. docker/nginx_with_ssl.conf.example file
-1.3. setup the server
-1.4. buy a domain name and link it with the droplet
-1.5. connect to the droplet via SSH
-1.6. create SWAP file in coreOs
-1.7. setup folders and env file
-1.8. SSL certificate with LetsEncrypt
-1.9. install docker-compose -2. [Deployment](#deployment)
-2.1. pull images
-2.2. setup database
-2.3. build assets
-2.4. prepare Elasticsearch (search engine)
-2.5. start all services +1.1. setup the server
+1.2. buy a domain name and link it with the droplet
+1.3. connect to the droplet via SSH
+1.4. prepare server
+1.5. setup folders and env file
+1.6. setup nginx file
+1.7. SSL certificate with LetsEncrypt
+1.8. requirements +2. [Install Fabmanager](#install-fabmanager)
+2.1. Add docker-compose.yml file
+2.2. pull images
+2.3. setup database
+2.4. build assets
+2.5. prepare Elasticsearch (search engine)
+2.6. start all services 3. [Generate SSL certificate by Letsencrypt](#generate-ssl-certificate-by-letsencrypt) 4. [Docker utils](#docker-utils) -5. [Fabmanager update](#fabmanager-update)
+5. [Update Fabmanager](#update-fabmanager)
5.1. Steps
5.2. Good to know ## Preliminary steps -### docker/env file +### setup the server + +Go to [DigitalOcean](https://www.digitalocean.com/) and create a Droplet with One-click apps **"Docker on Ubuntu 16.04 LTS"** (Docker and Docker-compose are preinstalled). +You need at least 2GB of addressable memory (RAM + swap) to install and use FabManager. +We recommend 4 GB RAM for larger communities. +Choose a datacenter. Set the hostname as your domain name. + +### buy a domain name and link it with the server + +1. Buy a domain name on [OVH](https://www.ovh.com/fr/) +2. Replace the IP address of the domain with the droplet's IP (you can enable the flexible ip and use it) +3. **Do not** try to access your domain name right away, DNS are not aware of the change yet so **WAIT** and be patient. + +### connect to the server via SSH + +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`. + +### prepare server + +We recommend you to : +- ugprade your system +- add at least 2GB of swap +- verify that you are using a connection via an SSH key. If so, you can set the root passord (for the debug console) and disable password connection. +To do this, you can use the following script : + +```bash +cd /root +git clone https://github.com/sleede/lazyscripts.git +cd lazyscripts/ +chmod a+x prepare-vps.sh +./prepare-vps +``` + + +### setup folders and env file + +Create the config folder: +```bash +mkdir -p /apps/fabmanager/config +``` Make a copy of the **docker/env.example** file and use it as a starting point. Set all the environment variables needed by your application. Please refer to the [FabManager README](https://github.com/LaCasemate/fab-manager/blob/master/README.md) for explanations about those variables. -### docker/nginx_with_ssl.conf.example file +Then, copy the previously customized `env.example` file as `/apps/fabmanager/config/env` + +### setup nginx file + +Create the nginx folder: +```bash +mkdir -p /apps/fabmanager/config/nginx +``` + +Customize the docker/nginx_with_ssl.conf.example file * 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) **Use nginx.conf.example if you don't want SSL for your app.** -### setup the server - -Go to [DigitalOcean](https://www.digitalocean.com/) and create a Droplet with operating system coreOS **stable**. -You need at least 2GB of addressable memory (RAM + swap) to install and use FabManager. -Choose a datacenter. Set the hostname as your domain name. - -### buy a domain name and link it with the droplet - -1. Buy a domain name on [OVH](https://www.ovh.com/fr/) -2. Replace the IP address of the domain with the droplet's IP (you can enable the flexible ip and use it) -3. **Do not** try to access your domain name right away, DNS are not aware of the change yet so **WAIT** and be patient. - -### connect to the droplet via SSH - -You can already connect to the server with this command: `ssh core@droplet-ip`. When DNS propagation will be done, you will be able to -connect to the server with `ssh core@your-domain-name`. - -### create SWAP file in coreOS - -Switch to sudo and create a swap file: - -```bash -sudo -i -touch /2GiB.swap -chattr +C /2GiB.swap -fallocate -l 2048m /2GiB.swap -chmod 600 /2GiB.swap -mkswap /2GiB.swap -``` - -Create file **/etc/systemd/system/swap.service**, filling it with the lines: - -```bash -[Unit] -Description=Turn on swap -[Service] -Type=oneshot -Environment="SWAPFILE=/2GiB.swap" -RemainAfterExit=true -ExecStartPre=/usr/sbin/losetup -f ${SWAPFILE} -ExecStart=/usr/bin/sh -c "/sbin/swapon $(/usr/sbin/losetup -j ${SWAPFILE} | /usr/bin/cut -d : -f 1)" -ExecStop=/usr/bin/sh -c "/sbin/swapoff $(/usr/sbin/losetup -j ${SWAPFILE} | /usr/bin/cut -d : -f 1)" -ExecStopPost=/usr/bin/sh -c "/usr/sbin/losetup -d $(/usr/sbin/losetup -j ${SWAPFILE} | /usr/bin/cut -d : -f 1)" -[Install] -WantedBy=multi-user.target -``` - -Then enable the service and start it: - -```bash -systemctl enable /etc/systemd/system/swap.service -systemctl start swap -exit -``` - -### setup folders and env file - -Create the config folder: -```bash -mkdir -p /home/core/fabmanager/config -``` - -Then, copy the previously customized `env.example` file as `/home/core/fabmanager/config/env` - -Create the nginx folder: -```bash -mkdir -p /home/core/fabmanager/config/nginx -``` - Then, -Copy the previously customized `nginx_with_ssl.conf.example` as `/home/core/fabmanager/config/nginx/fabmanager.conf` +Copy the previously customized `nginx_with_ssl.conf.example` as `/apps/fabmanager/config/nginx/fabmanager.conf` **OR** -Copy the previously customized `nginx.conf.example` as `/home/core/fabmanager/config/nginx/fabmanager.conf` if you do not want to use ssl (not recommended !). +Copy the previously customized `nginx.conf.example` as `/apps/fabmanager/config/nginx/fabmanager.conf` if you do not want to use ssl (not recommended !). ### SSL certificate with LetsEncrypt @@ -127,15 +110,15 @@ Let’s Encrypt certificates expire after 90 days, so automation of renewing you Here is the setup for a systemd timer and service to renew the certificates and reboot the app Docker container: ```bash -mkdir -p /home/core/fabmanager/config/nginx/ssl +mkdir -p /apps/fabmanager/config/nginx/ssl ``` -Run `openssl dhparam -out dhparam.pem 4096` in the folder /home/core/fabmanager/config/nginx/ssl (generate dhparam.pem file) +Run `openssl dhparam -out dhparam.pem 4096` in the folder /apps/fabmanager/config/nginx/ssl (generate dhparam.pem file) ```bash -mkdir -p /home/core/fabmanager/letsencrypt/config/ +mkdir -p /apps/fabmanager/letsencrypt/config/ ``` -Copy the previously customized `webroot.ini.example` as `/home/core/fabmanager/letsencrypt/config/webroot.ini` +Copy the previously customized `webroot.ini.example` as `/appsfabmanager/letsencrypt/config/webroot.ini` ```bash -mkdir -p /home/core/fabmanager/letsencrypt/etc/webrootauth +mkdir -p /apps/fabmanager/letsencrypt/etc/webrootauth ``` Run `docker pull quay.io/letsencrypt/letsencrypt:latest` @@ -149,7 +132,7 @@ Requires=docker.service [Service] Type=oneshot -ExecStart=/usr/bin/docker run --rm --name letsencrypt -v "/home/core/fabmanager/log:/var/log/letsencrypt" -v "/home/core/fabmanager/letsencrypt/etc:/etc/letsencrypt" -v "/home/core/fabmanager/letsencrypt/config:/letsencrypt-config" quay.io/letsencrypt/letsencrypt:latest -c "/letsencrypt-config/webroot.ini" certonly +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 ExecStartPost=-/usr/bin/docker restart fabmanager_nginx_1 ``` @@ -170,18 +153,37 @@ WantedBy=timers.target That's all for the moment. Keep on with the installation, we'll complete that part after deployment in the [Generate SSL certificate by Letsencrypt](#generate-ssl-cert-letsencrypt). -### Install docker-compose +### Requirements + + +Verify that Docker and Docker-composer are installed : +(This is normally the case if you used a pre-configured image.) ```bash -curl -L https://github.com/docker/compose/releases/download/1.7.1/docker-compose-`uname -s`-`uname -m` > ./docker-compose +docker info +docker-compose -v +``` + +Otherwise, you can install docker to ubuntu with the following instructions : +https://docs.docker.com/engine/installation/linux/ubuntu/#install-using-the-repository + +To install docker-compose : + +```bash +curl -L https://github.com/docker/compose/releases/download/1.13.0/docker-compose-`uname -s`-`uname -m` > ./docker-compose sudo mkdir -p /opt/bin sudo mv docker-compose /opt/bin/ sudo chmod +x /opt/bin/docker-compose ``` -Then copy docker-compose.yml to your app folder `/home/core/fabmanager`. -## Deployment + +## Install Fabmanager + +### Add docker-compose.yml file + +Copy docker-compose.yml to your app folder `/apps/fabmanager`. +The docker-compose commands must be launched from the folder `/apps/fabmanager`. ### pull images @@ -211,7 +213,7 @@ docker-compose run --rm fabmanager bundle exec rake db:seed # seed the database ### Generate SSL certificate by Letsencrypt -**Important: app must be run before starting letsencrypt** +**Important: app must be run on http before starting letsencrypt** Start letsencrypt service : ```bash @@ -219,7 +221,7 @@ sudo systemctl start letsencrypt.service ``` If the certificate was successfully generated then update the nginx configuration file and activate the ssl port and certificate -editing the file `/home/core/fabmanager/config/nginx/fabmanager.conf`. +editing the file `/apps/fabmanager/config/nginx/fabmanager.conf`. Remove your app container and run your app to apply the changes running the following commands: ```bash @@ -235,29 +237,43 @@ sudo systemctl start letsencrypt.timer (check) sudo systemctl list-timers ``` -## Docker utils +## Docker utils with docker-compose ### Restart app -`docker restart fabmanager-app` +`docker-compose restart fabmanager` ### Remove app -`docker rm -f fabmanager-app` +`docker-compose down fabmanager` + +### Restart all containers + +`docker-compose restart` + +### Remove all containers + +`docker-compose down` + +### Start all containers + +`docker-compose up -d` ### Open a bash in the app context -`docker exec -it fabmanager-app bash` +`docker-compose run --rm fabmanager bash` ### Show services status `docker-compose ps` -### Restart all services +### Restart nginx container -`docker-compose restart` +`docker-compose restart nginx` -## Fabmanager update + + +## update Fabmanager *This procedure updates fabmanager to the most recent version by default.* @@ -267,7 +283,7 @@ When a new version is available, this is how to update fabmanager app in a produ 1. go to your app folder - `cd fabmananger` + `cd /apps/fabmanager` 2. pull last docker images @@ -279,7 +295,7 @@ When a new version is available, this is how to update fabmanager app in a produ 4. remove old assets - `sudo rm -Rf public/assets/` + `rm -Rf public/assets/` 5. compile new assets