Deployment

Manual deployment

Use the Dockerfile-dev (or Dockerfile-prod, but requires SSL) and docker-compose.yaml file to host the final service. First build the Docker image and then use the compose file with docker compose up -d (Note, docker-compose is deprecated).

The latest docker image version for the development environment is provided via the registry of this project. Pull it with (after authentication)

docker pull registry.gitlab.com/dorfplauschturnier/sales-point:latest

For a local setup the development environment is sufficient but for a public hosting the production Rails environment should be used. However, this requires setting up proper SSL certificates.

!! The production environment currently does NOT enforce SSL!! This is because we only use it locally and thus have no simple SSL certificates available.

For full blown hosting these guides may help:

• https://www.reddit.com/r/selfhosted/comments/md0qrc/ssl_on_raspberry_pi_for_docker_apps
• https://github.com/Matho/dockerize_raspberry_pi

Continuous Integration

Instead of the following manual setup, we could use the Kamal flow. See https://rameerez.com/amal-tutorial-how-to-deploy-a-postgresql-rails-app/.

Build the Rails application image

The Rails application is packed into a docker image with the CI job build_image. We use kaniko to build the image in the pipeline as described here. A runner with a docker executor must be setup as described here. As alternative we could use a Docker in Docker approach. However, this would require privileged mode for the runner as therefore is a security risk.

Build the mdbook

The documentation is built following this guide. The mdbook installation is fixed to a specific version as explained here.

Deploy the documentation

The mdbook is automatically deployed to the Gitlab pages with the job deploy_doc.

Deploy Sales Point

Deploying Sales Point automated requires privileged rights on the hosting server to start up / refresh the docker compose service. The simplest solution would be to add the Gitlab runner user to the docker privileged group or configure the runner as privileged. However, this is a security problem and thus we opt for a semi-automated solution (we only have one physical runner available. With a dedicated host this could be handled with tags).

The pipeline only copies the newest docker-compose.yml file to a specified location on the host which must be made accessible to the Gitlab runner user. Then the re-run docker compose up -d manually after the image has been built. In case the change has a database migration, this migration must be started manually from within the container. For this login into the container and execute /bin/rails db:migrate.

To enable this copying a shell executor must be setup as Gitlab runner and the corresponding user must have access to the target location. See Raspberry Pi setup guide on how to setup the access on Linux.

Raspberry Pi setup

As a simple Gitlab runner a raspberry pi can be used and could also serve to host the website. The following guide targets the 64-bit OS!

SSH setup

SSH is deactivated per default on the raspberry pi os. A ssh access is useful but poses risks when exposed to the internet. Therefore, the ssh password login should be disabled except for local connections.

• Open sudo nano /etc/ssh/sshd_config
• Set PasswordAuthentication no
• Add exception for home network

  Match address 192.168.*.*
      PasswordAuthentication yes
  

• Restart the ssh service sudo service ssh restart

Docker for pipeline

Docker must be installed as explained here (64-bit OS).

Gitlab runner

To support the continuous integration install the Gitlab runner on the Raspberry Pi. Then register a runner with a docker executor and tag it accordingly. It must be tagged to match the tags defined in the .gitlab-ci.yml file.

Optionally, for a semi-automated deployment of a running Sales Point a shared folder must be created matching the DEPLOY_PATH value in .gitlab-ci.yml. In addition, a separate shell executor (a runner with shell executor) must be available with the tag specified in .gitlab-ci.yml. Assuming the Gitlab runner runs under the user gitlab-runner, do the following steps on the Raspberry Pi

• Create the new directory

  sudo mkdir -p <DEPLOY_PATH>
  

• Create a new group named sales-point and add all users which should have access

  groupadd sales-point
  usermod -aG sales-point gitlab-runner
  usermod -aG sales-point TheHosterUser # the user which will start the hosting
  

• Change the ownership

  chgrp -R sales-point <DEPLOY_PATH>
  chown sales-point <DEPLOY_PATH> # alternatively?
  

• Add reading, writing and execution permissions for the new group

  chmod -R g+rwX <DEPLOY_PATH>
  chmod 775 <DEPLOY_PATH>
  chmod g+s <DEPLOY_PATH>