This is a structure build to host services following our modules convention. It allows of tearing up and down modules and their services easily. The following repositories have been created by us following our convention so these are fully compatible to this structure:
- Trufi Server Modules Use this to host services necessary for apps built on our Trufi Core. These modules are used by our famous and very first Trufi App.
- Trufi Website Modules Use this to host services necessary to have a project website to show potential users your app build on our Trufi Core.
We use docker but not to make this cross-platform. This is intended to be used on Linux. We only use docker to make setups equal, easy for all admins and their systems, for security and troubleshooting concerns.
This repository contains a bunch of service „modules“. Each "module" has "services" and contains a README. Each service has a specified job and deals as a module component.
In order to be able to host multiple instances of a modules we also introduce the concept of a "city". Each city has a config in ./config directory and can have a different set of "modules" enabled. For example: city 'Germany-Hamburg' can have the modules tileserver, photon and otp enabled. Another city 'Bolivia-Cochabamba' can have the modules tileserver and otp enabled. You see here is photon missing and that is completely ok. Cities are strictly taken apart from each other.
At last we introduce "chiefs" which are all services specified in the docker-compose.yml at project root. They don't share the concept of modules and cities. As they don't share this concept you cannot add/remove them in the classical way with add_module/remove_module. Instead they will be ruled by server which creates/removes/starts/stops them automatically depending on what you do with the modules.
Extending Trufi Multi-Instance Server - add/remove chiefs
The city config files are located inside ./config folder, you can create a new one providing your own variables:
| variable | example | description |
|---|---|---|
| city | Bolivia-Cochabamba | Just Country-City name (required) |
| domain | cbba.trufi.app | The domain name of the city. If you use the mode virtual domains then be creative as this variable will then not be of use but needs to be available |
| ... (depends on module) | ... (depends on module) | ... (depends on module) |
Create a new one based on the already existing config files to get an idea of their internal structure. Do that for each city you want to host backend services for. You may want to remove the other configuration city files which are meant to provide examples. If there is only one city configuration file ending with .env left then you can use the commands without the <name of city> argument e.g. add_module tileserver or server up tileserver. But as soon as there are more than one then you need to specify <name of city> of course.
For other but important parameters which apply globally to all cities, we use a global configuration stored in file ./data/instance.conf.
| Variable | Example | Description |
|---|---|---|
| ssl | yes | Tells add_module to configure SSL for the particular city. Valid values are yes or no. |
| curmode | virtual domain | The nginx domain structure to use. Accepted values are virtual domain (all cities run under the same domain) and real domains (each city has its own domain). Tells add_module how to configure nginx. |
| intraweb | yes | Toggles the Intraweb feature on or off. Valid values are yes or no. The script add_module will read this setting to know wherever to create the configuration necessary for Intraweb.Documentation of Intraweb |
You can find all in the modules folder. Each module has a README file with more detailed info.
In order to add more modules compatible to trufi-server-modules like tsm-locaco you just have to do a git clone inside the modules folder, to execute modifyComposes.py and to work with it as you did with the other modules pre-installed.
Read more about including external modules
- Clone of course
- Rename the cloned repo
trufi-server-multidifferently as you want to have a custom name describing what your clone of this structure is for. You might want to rename the folder towebsite-servicesto host websites and web platforms such as dashboards for your customers. Orcity-servicesfor services related to city governance. - Clone a
modulesrepository into this one e.g. https://github.com/trufi-association/trufi-website-modules or https://github.com/trufi-association/trufi-server-modules - Execute
./initand answer the setup questions
TODO: Move somewhere else
Definitely you used our tools in the Trufi Server Resources you generate all the data you need for the backend tools here. Excellent because the structure there is to 100% compactible to this one and you don't need to figure out how to copy/move things over to here. See also the concept of Resource Binding we introduced. But anyway now come the smart people to play and you can be one of them.
To copy over the files to their appropriate location here you just need to do the following: In your very own copy of Trufi Server Resources go to its data directory and copy the content of the <Country-City> which holds your data. Paste them into the modules folder of this one and accept the merge with already existing data. Or to put it into the words/world of sysadmins just execute
cp -a ./trufi-server-resources/data/<Country-City>/* ./trufi-server-cities/modules --verboseThen rename all data folders inside the modules to data_Country-City e.g. data_Germany-Hamburg.
TO DO: Introduce autosetup to ease setting up a new city or update an existing one (script needs to be developed still)
We hide all (optional) services behind a nginx proxy which can handle the encryption for them. To make encrypted connections to that nginx proxy possible we need to issue a HTTPS certificate. Luckily there is Let’s Encrypt issuing them to anyone without the need to pay. This backend relies on the SSL/TLS certificate management infrastructure of the docker host (your linux system). There are multiple ways connecting the dots.
Our docker cief-nginx by default listens on the host port 8290 for HTTP and on 8300 for HTTPS requests. See changing ports of chief-nginx if you want to change that.
This requires the ssl variable in ./data/instance.conf set to yes before any execution of add_module. If you accidentally run add_module before doing that then use remove_module to remove the nginx configuration files as remove_module is the opposite of add_module.
In any case you need to run openssl dhparam -out ./data/nginx/inc/dhparam.pem 4096 after executing init to generate the dhparam file.
The docker container chief-nginx in our provided configuration expects to find the necessary files needed to answer https requests in the host path ./data/certbot/conf which is in its schematics equal to the well known /etc/letsencrypt. Of course this behaviour can be changed that the nginx docker container sees /etc/letsencrypt of your host directly although not recommended. This just adds one more security risk to manage. If you care about security you just put the files in ./data/certbot/conf you need for running this docker infrastructure. To put it in other words: If you have the following domains example.com , example.uk and example.org . The first domain example.com is used by your web server listening to port 80 and the others two are used by the nginx running in this docker infrastructure then just put the necessary files for HTTPS on example.uk and example.org into ./data/certbot/conf . This way you have /etc/letsencrypt on your host for the HTTPS server running on your host system serving example.com. The other one ./data/certbot/conf for the HTTPS server running for this infrastructure serving example.uk and example.org.
This is the setup on our own server and we provide a working example of our nginx configuration for Let's Encrypt stuff you can use as an inspiration on how to do that thing.
This requires the ssl variable in ./data/instance.conf set to no before any execution of add_module. If you accidentally run add_module before doing that then use remove_module to remove the configuration files as remove_module is the opposite of add_module.
This is useful if you are already providing other services in need of HTTPS to your customers e.g. you are already hosting a website. Now you want to have your server provide different services for different cities. Also this is your only option if your server is behind a firewall just letting port 80 and 443 pass through. Go setup nginx on your host which then does all the HTTPS stuff and takes care to redirect to the appropriate sub webservers based on specified parameters you have defined. This allows you to use this structure without any HTTPS configuration ( ssl="no" ) because encryption is handled by your HTTPS server on your host.
See an example nginx configuration only used for Let's Encrypt
We created a highly flexible script to ease HTTPS certificate creation and it accounts for:
- construction of the command to pass to
certbot - allows to specify a
<webroot>which allows you to specify the path to the folder where your web server on the host or in another docker container running on port80serves the./well-knownfrom. - creation of a systemd timer to automatically renew the certificate
Usage: certify <Country-City <webroot>
Example: certify Germany-Hamburg /srv/trufi/nginx/www
For a list of available commands see the command documentation