This document will guide you through all the steps needed to set up your Fab-manager app on a production server, based on a solution using Docker and Docker-compose.

In order to make it work, please use the same directories structure as described in this guide in your Fab-manager app folder. You will need to be root through the rest of the setup.

1. Preliminary steps
   1.1. Setup the server
   1.2. Setup the domain name
   1.3. Connect through SSH
   1.4. Prepare the server
   
2. Install Fab-manager
   
3. Useful commands
4. Update Fab-manager
   4.1. Scripted update
   4.2. Update manually
   4.2.2. Manual update steps
   4.3. Upgrade to the last version
   4.4. Upgrade to a specific version
   4.4.1. With scripted update
   4.4.2. With manual update
   

There are many hosting providers on the internet, providing affordable virtual private serveurs (VPS). Choose one, depending on your budget, on the server's location, on the uptime guarantee, etc.

To install or upgrade Fab-manager you need at least 4 GB of RAM + 2 GB of swap to be able to compile the assets.

Once installed, if you do not plan to use the statistics module, you will need at least 2 GB of addressable memory (RAM + swap) to use Fab-manager. We recommend 4 GB of RAM to take full advantage of Fab-manager and be able to use the statistics module. If you have a large community (~ 200 active membres), we recommend 4 GB of RAM, even without the statistics module.

During the installation and the upgrades, the assets' compilation phase may fail if you do not have sufficient available memory.

Supported operating systems are Ubuntu LTS 16.04+ and Debian 8+ with an x86 64-bits architecture. This might work on other linux systems, and CPU architectures but this is untested for now, and we do not recommend for production purposes.

curl and bash are needed to retrieve and run the automated deployment scripts. Then the various scripts will check for their own dependencies.

Moreover, the main software dependencies to run fab-manager are Docker v20.10 or above and Docker Compose They can be easily installed using the prepare-vps.sleede.com script below.

There are many domain name registrars on the internet, choose one that fit your needs.

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 of type A)
3. Do not try to access your domain name right away, DNS are not aware of the change yet so WAIT and be patient.
4. You may want to bind the subdomain www. to your main domain name. You can achieve this by creating a DNS record of type CNAME.

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.

Before installing Fab-manager, we recommend you to:

• Upgrade your system
• Set up the server timezone
• Add at least 2 GB of swap memory
• Protect your SSH connection by forcing it through an RSA key

You can run the following script as root to easily perform all these operations:

\curl -sSL prepare-vps.sleede.com | bash

Run the following command to install Fab-manager. This script will guide you through the installation process by checking the requirements and asking you the configuration elements.

\curl -sSL setup.fab.mn | bash

OR, if you don't want to install Fab-manager in /apps/fabmanager, use the following instead:

\curl -sSL setup.fab.mn | bash -s "/my/custom/path"

If your server machine is not powerful, you can lower the system requirements by uninstalling ElasticSearch. In order to remove ElasticSearch, you must first disable the statistics module from Customization > General > Modules.

Then, you can remove the elasticsearch service from the docker-compose.yml file and restart the whole application:

docker compose down && docker compose up -d

Disabling ElasticSearch will save up to 800 Mb of memory.

Below, you'll find a collection of useful commands to control your instance with docker-compose. Before using any of these commands, you must first cd into the app directory.

• Read again the environment variables and restart

docker compose down && docker compose up -d

• Open a bash prompt inside the app container

docker compose exec fabmanager bash

• Open the ruby console in the application

\curl -sSL run.fab.mn | bash

• Show services status

docker compose ps

• Run a command and provide it environment variables

docker compose run --rm -e VAR1=xxx -e VAR2=xxx fabmanager bundle exec rails my:command

When a new version is available, follow this procedure to update Fab-manager in a production environment. You can subscribe to this atom feed to get notified when a new release comes out.

Starting with Fab-manager v4.5.0, you can upgrade Fab-manager in one single easy command, specified in the GitHub releases notes. To upgrade multiple versions at once, read the GitHub release notes of all versions between your current version, and the target version.

You MUST append all the arguments of the upgrade commands, for each version, to the command you run.

E.g. If you upgrade from 1.2.3 to 1.2.6, with the following release notes:

## 1.2.4
\curl -sSL upgrade.fab.mn | bash -s -- -e "VAR=value"
## 1.2.5
\curl -sSL upgrade.fab.mn | bash -s -- -c "rails fablab:setup:command"
## 1.2.6
\curl -sSL upgrade.fab.mn | bash -s -- -p "rails fablab:do:things"

Then, you'll need to perform the upgrade with the following command:

\curl -sSL upgrade.fab.mn | bash -s -- -e "VAR=value" -p "rails fablab:do:things" -c "rails fablab:setup:command"

⚠ Do not confuse commands prefixed with -p and with -c because they are not intended to run at the same moment of the upgrade process.

If you upgrade Fab-manager from a version >= 4.5.0, we recommend using the upgrade script above.

⚠ If you are upgrading from a very outdated version, you must first upgrade to these versions in order:

• v2.8.3
• v3.1.2
• v4.0.4
• v4.4.6
• v4.7.13 After that, you can finally update to the last version

⚠ With versions < 4.3.3, you must replace bundle exec rails with bundle exec rake in all the commands above

0. Read carefully the changelog of the last version you are upgrading to. It will contain important instructions about the upgrade process.

1. Go to your app folder

   cd /apps/fabmanager

2. Pull last docker images

   docker compose pull

3. Stop the app

   docker compose stop fabmanager

4. Remove old assets

   rm -Rf public/packs/ public/assets/

5. Compile new assets

   docker compose run --rm fabmanager bundle exec rails assets:precompile

6. Run specific commands

   Do not forget to check if there are commands to run for your upgrade. Those commands are always specified in the CHANGELOG and prefixed by [TODO DEPLOY].

   Those commands execute specific tasks and have to be run manually. You must prefix the commands starting by rails... or rake... with: docker compose run --rm fabmanager bundle exec. In any other cases, the other commands (like those invoking curl \curl -sSL... | bash) must not be prefixed. You can also ignore commands only applicable to development environnement, which are prefixed by (dev) in the CHANGELOG.

7. Restart all containers

     docker compose down
     docker compose up -d

You can check that all containers are running with docker compose ps.

It's the default behaviour as docker compose pull command will fetch the latest versions of the docker images. Be sure to run all the specific commands listed in the CHANGELOG between your actual, and the new version in sequential order. Example: to update from v2.4.0 to v2.4.3, you will run the specific commands for the v2.4.1, v2.4.2 and v2.4.3.

The easiest way to proceed is to provide the target version to the upgrade script, with the -t parameter, like this:

\curl -sSL upgrade.fab.mn | bash -s -- -t 4.7.13

If you are upgrading manually, edit your /apps/fabmanager/docker-compose.yml file and change the following line:

image: sleede/fab-manager

For example, here we want to use the v3.1.2:

image: sleede/fab-manager:release-v3.1.2

Then run the normal upgrade procedure.