Quollix

Mon, 01 Jan 0001 00:00:00 +0000

Frontend Development Workflow

Persistent Development State

When starting Quollix in TEST mode, you can use the -k flag which preserves database is preserved across restarts and preserves Login state, so you do not need to log in again after each backend code change and restart.

Quollix uses SSR with Go HTML templates.

When running in TEST mode:

Backend code changes still require a container restart
Frontend resource changes do not require a restart

Instead, the GUI provides a Reload Frontend button:

Architecture

Mon, 01 Jan 0001 00:00:00 +0000

Quollix is a monolithic application that runs on a single server. Each HTTP request from users is either processed by Quollix directly or passes through Quollix and is proxied to an app. The apps are “hidden” behind Quollix. This way, Quollix serves as an extra layer of security, as only authenticated users have access to the apps by default.

For security reasons, each app runs in its own isolated space with its unique Docker network and volumes. So, apps are isolated from each other.

Local Development

Mon, 01 Jan 0001 00:00:00 +0000

For local development, you should run Quollix in TEST mode docker container using the ci-runner tool. This mode is optimized for development and testing, so there are some features implemented which make the development experience smoother. This includes:

when running docker container in test mode, you can add the flag -k to keep the database and uploaded files between restarts. This way, you don’t have to login or set up everything from scratch on each change of backend code and subsequent restart.
Changing web resource files (HTML, CSS, JS) on the host system can be reloaded from the GUI, so no restart is necessary.
a dummy SSH server is started to allow SSH connections and creating backups.
test-apps can be loaded dynamically into Quollix’s local test environment, allowing developers to modify docker-compose.yml files and immediately validate their integration with Quollix features such as network accessibility and OIDC.
Usually when working with test apps, you might need a valid TLS certificate for testing integration with Quollix as an OIDC provider.
- Set the domain in the /etc/hosts file to point to localhost (e.g. quollix.test.quollix.org -> 127.0.0.1), do this also with all expected app domains.
- Run Quollix in prod mode
- Set a test domain in the settings that you own (e.g. we usually use test.quollix.org)
- Generate a TLS certificate via DNS-01 challenge
- Download the generated certificate (certificate.pem)
- Stop Quollix and restart it in TEST mode
- Set the host again and upload the previously downloaded certificate
- Restart your browser and revisit Quollix under quollix.<test-domain> (for example quollix.test.quollix.org)

For local development, Quollix should usually be run in TEST mode inside a Docker container using the ci-runner tool. TEST mode provides features optimizing development.

OIDC Integration Testing Strategy

Mon, 01 Jan 0001 00:00:00 +0000

This article describes the recommended strategy for testing OIDC integrations in a local development setup between apps and Quollix.

Theory

Quollix acts as the OIDC provider. Apps act as OIDC clients.
Apps started by Quollix resolve the OIDC provider via the domain quollix.<host> inside the shared Docker network.
Many OIDC clients require the provider’s endpoints to be served over HTTPS with a valid TLS certificate.
Quollix’s well-known endpoint is available at quollix.<host>/.well-known/openid-configuration.
While some apps may allow self-signed certificates, using a valid certificate is the safest option and avoids the need to relax or disable client-side TLS verification.
Quollix can automatically generate and manage certificates for a test domain, making it easy to reproduce a production-like setup locally.

Test Apps

For integration testing, apps are provided as Docker Compose YAML files located in the test-apps folder on the host system. When Quollix is running in TEST mode, these apps are loaded into an App Store mock so that they can be installed as if from a real App Store. This enables local development and testing of app integrations before publishing them to the real App Store.