Skip to main content

Prerequisite

In order to install your own voca, you will need the following at your hand:

An account in a Jelastic Virtuozzo PAAS service

To install your own, you will first need a Virtuozzo Provider. This is a must-have for Voca for now. To find a Virtuozzo Provider in your country, you can look at their directory: https://www.virtuozzo.com/application-platform-partners/. As you can understand, this system allows us to spread Voca and local sovereignty faster.

Access to your DNS provider

We will set wild-card DNS entry to be able to define user’s decidim default adresses.

A no-reply dedicated email

All the decidim will use the same no-reply email address by default. Be sure to have a dedicated email address that can handle enough traffic, and exists.

Basics of docker-compose

Even Jelastic Virtuozzo doesn’t uses docker-compose, it uses the same logics. Entrypoints, commands, volumes and links are fundamentals you must know before going further.

Infrastructure: a closer look​

We will walk you through the process of setting up your own Voca, node by node:

  1. Set up a load balancer with Traefik
  2. Set up voca backend
    1. Postgres
    2. Redis
  3. Set up voca frontend
  4. Configure voca traefik
  5. Wrap-up

After installation, we will examine the relationships between these components and discuss configuration methods.

Lastly, we will set up volumes that will be backed up as part of our backup workflow.

Set up a load balancer with Traefik​

We will now create our first environment that will host only our traefik instance. This is a good practice to be able to ease the setup firewalls afterward, and secure your internal trafic.

Environment variables for the traefik environment are documented directly in the repository: https://git.octree.ch/decidim/vocacity/system/-/blob/main/contrib/traefik/README.md

You will need to setup a voca backend and frontend before beeing able to have your traefik image fully functional.

ℹ️ octree/voca-traefik images use its environment at entrypoint to generate configuration files. If you update the container’s environment you MUST restart it.

Set up voca backend and workers​

Voca work with a strapi backend and a next frontend. Within the strapi backend, you can start the API, or the voca workers. Here what they are accountable for:

  • API: gives the frontend all the data layer needed, through an authentication/permission system.
  • Frontend: Display the app for the user
  • Worker “install”: will install new environment and do long tasks
  • Worker “main”: will do short and fast tasks

Backend​

ℹ️ To generate a strong password, consider using gpg: gpg --gen-random --armor 1 64
Password sizes matters, here a simple rules:

  • Salts > 128chars
  • Token, DB passwords, etc: > 64chars

Once you have a working backend environment, you will need to set the node IPv4 as environment variable of the traefik:

Copy this ipv4 and paste it in the traefik environment variable named TRAEFIK_BACKEND_URL. For example, in this case you will paste http://10.102.7.81

Frontend​

To link the frontend to the backend, you need to insert the backend local ipv4 in the frontend environment variable STRAPI_URL. For this, open the frontend environment, go to environment variables, and set: STRAPI_URL http://<backend local ipv4>

Once you have a working frontend environment, you will need to set the node IPv4 as environment variable of the traefik:

Copy this ipv4 and paste it in the traefik environment variable named TRAEFIK_FRONTEND_URL. For example, in this case you will paste http://10.102.5.77

Jelastic Token​

Your api will need to work with a jelastic token. This enables the API to work with jelastic and order new deployments.

Once you have your jelastic token, you MUST define the environment variables for the API environment:

  • JELASTIC_HOST: your jelastic hoster, like app.<hoster>.com
  • JELASTIC_TOKEN: the token you just got
  • JELASTIC_UNSAFE_OPERATIONS: 0 if you want to be sure voca will never destroy environment. (set 1 for development environments)
  • VOCA_DEFAULT_ENVGROUP : the tag that will be affected to all new instance. default: vocacity/voca-dev
  • More information in the Readme. https://git.octree.ch/decidim/vocacity/system/-/blob/main/backend/README.md?ref_type=heads

Setup DNS​

You will need to setup three entries in your DNS:

  • api.<my-host>
  • app.<my-host>
  • *.<my-host>

These DNS will all have a A RECORD of the traefik public IP.

NameTypeTTLDestination
*.demo.voca.cityA1080045.66.223.237
app.demo.voca.cityA1080045.66.223.237
api.demo.voca.cityA1080045.66.223.237

Once it is done, you will need to set few environments values:

  • in the octree/voca-traefik
    • TRAEFIK_BACKEND_HOST = api.demo.voca.city
    • TRAEFIK_FRONTEND_HOST = app.demo.voca.city
  • in the octree/voca-backend
    • HOST to api.demo.voca.city
  • in the octree/voca-frontend
    • NEXTAUTH_URL to app.voca.city

Please restart all the installed node before checking if its work.