IPA Toolkit
platform

The IPA Toolkit implements helpful tools to master the mighty IPA process. This is the platform repository, which contains aids to configure the whole system.

Getting started

The following steps describe how to set up the IPA toolkit.

Environment

These steps describe how to set up the system environment on Ubuntu 22.04 LTS:

1. Install updates

   apt update && apt upgrade

2. Install Docker dependencies

   apt install apt-transport-https ca-certificates curl gnupg lsb-release

3. Import Dockers GPG key

   curl -fsSL https://download.docker.com/linux/ubuntu/gpg | gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

4. Add Dockers apt repository

   • On x86_64

     echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null

   • On ARM

     echo "deb [arch=arm64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | tee /etc/apt/sources.list.d/docker.list > /dev/null

5. Install Docker

   apt update && apt install docker-ce docker-ce-cli containerd.io

6. Create directory for Docker cli plugins

   mkdir -p /usr/local/lib/docker/cli-plugins

7. Download docker-compose executable

   • On x86_64

     curl -SL https://github.com/docker/compose/releases/download/v2.4.1/docker-compose-linux-x86_64 -o /usr/local/lib/docker/cli-plugins/docker-compose

   • On ARM

     curl -SL https://github.com/docker/compose/releases/download/v2.4.1/docker-compose-linux-aarch64 -o /usr/local/lib/docker/cli-plugins/docker-compose

8. Give executable permission to Docker Compose

   chmod +x /usr/local/lib/docker/cli-plugins/docker-compose

9. Validate the installation of Docker (>= 20.10.17)

   docker version

10. Validate the installation of Docker Compose (>= 2.4.1)

    docker compose version

The following sources were used:

• Documentation: Docker
• Documentation: Docker Compose V2

Application system

1. Install git

   apt install git

2. Clone this repository

   cd /srv && git clone https://github.com/swissictedu/ipa-toolkit-platform

3. Copy the docker-compose.yml.

   cp docker-compose.yml docker-compose.prod.yml

4. Make sure that the DNS is routing all subdomains to the host where the individual services run on.

5. Replace all example.com with the domain where the application runs on.

   sed -i "s/example.com/example.ch/g" docker-compose.prod.yml

6. Change contact email for SSL certificates in traefik.yml

7. Configure the following environment variables in docker-compose.prod.yml:

   • ipa-toolkit-backend
     • DEFAULT_HOST: The backends hostname
     • SECRET_KEY_BASE: Generate with rails secret or openssl rand -hex 64
     • SYSTEM_EMAIL_SERVER: SMTP server
     • SYSTEM_EMAIL_DOMAIN: Domain
     • SYSTEM_EMAIL_ADDRESS: E-mail account address (username)
     • SYSTEM_EMAIL_PASSWORD: E-mail account password
   • ipa-toolkit-frontend
     • API: Escape uri so it works with sed (e.g. "https:\\/\\/api.example.com\\/graphql")

8. Run application system

   docker compose -f docker-compose.prod.yml up -d

9. Initialize database

   1. Create database

      docker exec -it $(docker ps -f name=ipa-toolkit-backend -q) rails db:create

   2. Load database schema

      docker exec -it $(docker ps -f name=ipa-toolkit-backend -q) rails db:schema:load

   3. Create administrator account

      docker exec -it $(docker ps -f name=ipa-toolkit-backend -q) rails db:seed

Release a new version

1. Merge the release pull request and wait for completion of the pipeline.

Upgrade application system

1. Pull new images

   docker compose -f docker-compose.prod.yml pull

2. Recreate containers

   docker compose -f docker-compose.prod.yml up -d

3. Migrate database

   docker exec -it $(docker ps -f name=ipa-toolkit-backend -q) rails db:migrate

Maintain application system

• Create a database backup

  docker exec -it $(docker ps -f name=ipa-toolkit-backend -q) pg_dumpall -c -U postgres > toolkit_dump_`date +%d-%m-%Y"_"%H_%M_%S`.sql

• Archive storage

  tar -czvf toolkit_storage_`date +%d-%m-%Y"_"%H_%M_%S`.tar.gz /var/lib/docker/volumes/ipa-toolkit-platform_storage/_data/