diff --git a/README.md b/README.md index 6be669f2..6c4eca60 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,43 @@ # FAF Stack -This repository aims to provide a ready-to-go Docker Compose file to set up a complete FAF stack (or parts of it) with -a single command. +This repository aims to provide a ready-to-go Docker Compose setup for managing the complete FAF stack (or parts of it) with simple commands. + +The FAF production and test server use this repository and therefore guarantee close-to-production readyness. ## Structure -The FAF stack uses two directories: +The FAF stack consist of multiple components: + +* Service definitions in .yml files +* Global and application level configuration +* Application data + +This repository contains only templates of the configuration and no data. "Real" configuration and data are excluded by `.gitignore`. In fact, all files and directories are excluded if not explicitly un-ignored within `.gitignore`. The data directory will be automatically created. + +### Service definitions -* `config` contains the configuration files for all FAF services -* `data` contains data required or produced by the services +FAF is a very complex infrastructure. In order to make it easier for new developers to get into it, we split the services across multiple docker-compose files: -Both directories are excluded by `.gitignore`. In fact, all files and directories are excluded if not explicitly un-ignored within `.gitignore`. +* `docker-compose.yml` contains all **core** services of FAF. If you want to start developing for FAF you can concentrate on this particular file. +* `faf-extra.yml` contains services for the FAF community which are not required for the core infrastructure to run. +* `monitoring.yml` contains dedicated monitoring applications which provide insights on the load and behavior of the FAF applications ### Configuration -Each service has its own directory within `config`. They usually contain an environment file and/or other configuration -files needed for the service to operate properly. Environment files are loaded by Docker Compose and additional -files/directories may be mounted as volumes (both as specified in `docker-compose.yml`). +On root level there needs to be an `.env` file which contains some global setup. -The `config` directory does not exist and has to be copied from `config.templates`. After that, it has to be kept in sync -with updates to `config.templates` manually (like when a parameter has been added, renamed or removed). +Each service has its own directory within `config`. They usually contain an environment file and/or other configuration files needed for the service to operate properly. Environment files are loaded by Docker Compose and additional files/directories may be mounted as volumes (both as specified in their respective `.yml` file). + +The `config` directory does not exist and has to be copied from `config.templates`. After that, it has to be kept in sync with updates to `config.templates` manually (like when a parameter has been added, renamed or removed). +If you don't need / want to change the application config, you could also create a **symlink** from `config.template` to `config`. This way you will always have the latest default config. ### Data Some services need to persist files in volumes, or read files of other services. All volumes are created inside the `data` directory. +**Attention Windows users**: Docker for Windows has some troubles mounting volumes to your hard disk. You need to configure access to the drive and even then some services might refuse to work. For a better experience we recommend using a virtual machine running Linux or at least running docker in the Windows Subsystem for Linux (WSL). + ## Naming To keep things intuitive and avoid conflicts, all services, network aliases, user names, folder names and environment files follow a @@ -35,8 +47,8 @@ consistent naming. ### Prerequisites -* [Docker](https://github.com/docker/docker/releases) 19.03.5-ce or newer (or [Docker Toolbox](https://github.com/docker/toolbox/releases)) -* [Docker Compose](https://github.com/docker/compose/releases) v1.24.1 or newer +* [Docker](https://github.com/docker/docker/releases) 20.10.7-ce or newer +* [Docker Compose](https://github.com/docker/compose/releases) v1.28.6 or newer (It might work with older versions but is not tested on these.) @@ -53,34 +65,19 @@ In folder `config/faf-java-api/pki` replace `private.key` and `public.key` with Hint: Some linux distros generate 3072 bit RSA keys by default (e.g. Arch). 3072 bit is not supported. Please use 2048 bit or 4096 bit key length. -### Initialize core database +### Initialize core services scripts/init-db.sh - -This will launch the faf-db and generate the current database scheme. + scripts/init-rabbitmq.sh + scripts/init-hydra.sh + scripts/create-hydra-test-clients.sh + +This will launch some core services and generate users, database schemas and OAuth clients. ### Update database schema docker-compose run --rm faf-db-migrations migrate -### Start all at once - - docker-compose up -d - -### Start a single service - -If you start a single service, services it depends on will be started automatically. For instance: - - docker-compose up -d faf-python-server - -### Start from local repository - -To start a service from your local repository, find its `image` or `build` in the `docker-compose.yml` and change it to: - - build: - -Where `` is the path to your local project, for instance `../faf-python-server`. - # Service specific configurations ## Postal