Anthias/docs/developer-documentation.md

Developer documentation

Understanding the components that make up Anthias

Here is a high-level overview of the different components that make Anthias:

These components and their dependencies are mostly installed and handled with Ansible and Docker.

• The NGINX component (anthias-nginx) forwards requests to the backend and serves static files. It also acts as a reverse proxy.
• The viewer (anthias-viewer) is what drives the screen (e.g., shows web page, image or video).
• The web app component (anthias-server) — which consists of the front-end and back-end code – is what the user interacts with via browser.
• The Celery (anthias-celery) component is for aynschronouslt queueing and executing tasks outside the HTTP request-response cycle (e.g., doing assets cleanup).
• The WebSocket (anthias-websocket) component is used for forwarding requests from NGINX to the backend.
• Redis (redis) is used as a database, cache and message broker.
• The database component uses SQLite for storing the assets information.

Dockerized development environment

To simplify development of the server module of Anthias, we've created a Docker container. This is intended to run on your local machine with the Anthias repository mounted as a volume.

Do note that Anthias is using Docker's buildx for the image builds. This is used both for cross compilation as well as for local caching. You might need to run docker buildx create --use first.

Assuming you're in the source code repository, simply run:

$ ./bin/build_containers.sh
$ docker compose \
    -f docker-compose.dev.yml up

Building containers locally

Make sure that you have buildx installed and that you have run docker buildx create --use before you do the following:

$ ./bin/build_containers.sh

Skipping specific services

Say that you would like to skip building the anthias-viewer and anthias-nginx services. Just run the following:

$ SKIP_VIEWER=1 SKIP_NGINX=1 ./bin/build_containers.sh

Generating only Dockerfiles

If you'd like to just generate the Dockerfiles from the templates provided inside the docker/ directory, run the following:

$ DOCKERFILES_ONLY=1 ./bin/build_containers.sh

Testing

Running the unit tests

Build and start the containers.

$ SKIP_SERVER=1 \
  SKIP_WEBSOCKET=1 \
  SKIP_NGINX=1 \
  SKIP_VIEWER=1 \
  SKIP_WIFI_CONNECT=1 \
  ./bin/build_containers.sh
$ docker compose \
    -f docker-compose.test.yml up -d

Run the unit tests.

$ docker compose \
    -f docker-compose.test.yml \
    exec anthias-test bash ./bin/prepare_test_environment.sh -s

# Integration and non-integration tests should be run separately as the
# former doesn't run as expected when run together with the latter.

$ docker compose \
    -f docker-compose.test.yml \
    exec anthias-test ./manage.py test --exclude-tag=integration

$ docker compose \
    -f docker-compose.test.yml \
    exec anthias-test ./manage.py test --tag=integration

The QA checklist

We've also provided a checklist that can serve as a guide for testing Anthias manually.

Generating CSS and JS files

Anthias only supports compiling from the host container at the moment. You need to install the latest version of Node.js. We recommend to intall Node.js on Linux. You can use this guide to get started.

Installing Node.js dependencies

Run the following command from the project root directory.

$ npm install

Transpiling CSS from SASS

$ npm run sass-dev

Transpiling JS from CoffeeScript

# You need to run this on a separate terminal session if you already ran the
# script for transpiling SASS files.
$ npm run coffee-dev

Closing the transpiler

Just press Ctrl-C to close the SASS and CoffeeScript transpilers.

Linting Python code locally

The project uses flake8 for linting the Python codebase. While the linter is being run on the CI/CD pipeline, you can also run it locally. There are several ways to do this.

Run the linter using act

act lets you run GitHub Actions locally. This is useful for testing the CI/CD pipeline locally. Installation instructions can be found here.

After installing and setting up act, run the following command:

$ act -W .github/workflows/python-lint.yaml

The command above will run the linter on the all the Python files in the repository. If you want to run the linter on a specific file, you can try the commands in the next section.

Running the linter using Poetry

You have to install Poetry first. You can find the installation instructions here.

After installing Poetry, run the following commands:

# Install the dependencies
$ poetry install --only=dev-host
$ poetry run flake8 $(git ls-files '**/*.py')

To run the linter on a specific file, run the following command:

$ poetry run flake8 path/to/file.py

Managing releases

Creating a new release

Check what the latest release is:

$ git pull
$ git tag

# Running the `git tag` command should output something like this:
# 0.16
# ...
# v0.18.6

Create a new release:

$ git tag -a v0.18.7 -m "Test new automated disk images"

Push release:

$ git push origin v0.18.7

Delete a broken release

$ git tag -d v0.18.5                         [±master ✓]
Deleted tag 'v0.18.5' (was 9b86c39)

$ git push --delete origin v0.18.5           [±master ✓]

Directories and files explained

In this section, we'll explain the different directories and files that are present in a Raspberry Pi with Anthias installed.

home/${USER}/screenly/

• All of the files and folders from the Github repo should be cloned into this directory.

/home/${USER}/.screenly/

• default_assets.yml — configuration file which contains the default assets that get added to the assets list if enabled
• initialized — tells whether access point service (for Wi-Fi connectivity) runs or not
• screenly.conf — configuration file for web interface settings
• screenly.db – database file containing current assets information.

/etc/systemd/system/

• wifi-connect.service — starts the Balena wifi-connect program to dynamically set the Wi-Fi config on the device via the captive portal
• anthias-host-agent.service — starts the Python script host_agent.py, which subscribes from the Redis component and performs a system call to shutdown or reboot the device when the message is received.

/etc/sudoers.d/screenly_overrides

• sudoers configuration file that allows pi user to execute certain sudo commands without being a superuser (i.e., root)

/usr/share/plymouth/themes/anthias

• anthias.plymouth — Plymouth config file (sets module name, ImageDir and ScriptFile dir)
• anthias.script – plymouth script file that loads and scales the splash screen image during the boot process
• splashscreen.png — the spash screen image that is displayed during the boot process

Debugging the Anthias WebView

export QT_LOGGING_DEBUG=1
export QT_LOGGING_RULES="*.debug=true"
export QT_QPA_EGLFS_DEBUG=1

The Anthias WebView is a custom-built web browser based on the Qt toolkit framework. The browser is assembled with a Dockerfile and built by a webview/build_qt#.sh script.

For further info on these files and more, visit the following link: https://github.com/Screenly/Anthias/tree/master/webview