Systemd Services
All Phonemos components are managed as systemd services. Each service runs as the phonemos user and uses Docker Compose to start containers.
Service Unit | Description | Containers |
|---|---|---|
phonemos-keycloak | Authentication | keycloak, keycloak-postgres |
phonemos-rustfs | Object storage | rustfs-filestore, createbuckets |
phonemos-ingress | Reverse proxy | ingress (Nginx) |
phonemos-postgres | Main database | postgres |
phonemos | Application stack | hasura, backend, backend-pdf, frontend, redis, pandoc, confluence-converter, converter-plantuml, converter-latex, converter-browser-widget-renderer, converter-linux-tools, converter-libreoffice |
phonemos-connector-youtrack | YouTrack connector | YouTrack connector (optional) |
phonemos-connector-jira-dc | Jira DC connector | Jira DC connector (optional) |
Connector services are only enabled if the corresponding option was selected during setup (ENABLE_YOUTRACK / ENABLE_JIRA_DC in /etc/phonemos/setup.conf).
Basic Commands
Check Status
1
2
3
4
5
# Status of a single service
sudo systemctl status phonemos-keycloak
# Status of all Phonemos services
sudo systemctl status phonemos-*Start a Service
1
sudo systemctl start phonemos-keycloakStop a Service
1
sudo systemctl stop phonemos-keycloakRestart a Service
1
sudo systemctl restart phonemos-keycloakEnable / Disable at Boot
1
2
3
4
5
# Enable (start automatically on boot)
sudo systemctl enable phonemos-keycloak
# Disable (do not start on boot)
sudo systemctl disable phonemos-keycloakRecommended Start Order
Services should be started in the following order to satisfy dependencies:
Order | Service | Rationale |
|---|---|---|
1 | phonemos-keycloak | Keycloak must be running for authentication to work. Its internal PostgreSQL starts first via a health check dependency. |
2 | phonemos-rustfs | Object storage must be available before the application starts. The createbuckets init container creates required buckets. |
3 | phonemos-ingress | The reverse proxy must be running to route external traffic. Requires TLS certificates to be in place. |
4 | phonemos-postgres | The main database must be available before hasura and backend start. |
5 | phonemos | The main application stack. Hasura waits for its health check (60s start period) before backend starts (120s start period). |
6 | phonemos-connector-youtrack | Optional. Only if enabled. |
7 | phonemos-connector-jira-dc | Optional. Only if enabled. |
To start all services in order:
1
2
3
4
5
sudo systemctl start phonemos-keycloak
sudo systemctl start phonemos-rustfs
sudo systemctl start phonemos-ingress
sudo systemctl start phonemos-postgres
sudo systemctl start phonemosTo stop all services:
1
2
3
4
5
6
7
sudo systemctl stop phonemos
sudo systemctl stop phonemos-connector-youtrack
sudo systemctl stop phonemos-connector-jira-dc
sudo systemctl stop phonemos-ingress
sudo systemctl stop phonemos-postgres
sudo systemctl stop phonemos-rustfs
sudo systemctl stop phonemos-keycloakHealth Checks
Docker Compose health checks are configured for critical services. These determine when dependent services can start.
Container | Health Check | Interval | Start Period |
|---|---|---|---|
hasura | curl -f http://localhost:8080/healthz | 10s | 60s |
backend | wget --spider http://localhost:8080/health | 10s | 120s |
backend-pdf | curl -f http://localhost:8080/api/pdf/health | 10s | -- |
postgres | pg_isready --user=postgres | 10s | -- |
keycloak-postgres | pg_isready --user=postgres | 10s | -- |
rustfs-filestore | curl -fsS http://localhost:9000/health | 10s | 120s |
frontend | curl -f http://localhost:8080/ | 10s | -- |
confluence-converter | curl -f http://localhost:8080/health | 10s | -- |
In-Container Dependencies
Within the phonemos service unit, Docker Compose enforces ordering:
backend starts after hasura is healthy.
backend-pdf starts after hasura is healthy.
keycloak starts after keycloak-postgres is healthy.
Converter services start after redis is running.
Viewing Logs
Systemd Journal
1
2
3
4
5
6
7
8
# Follow logs for all Phonemos services
sudo journalctl -u phonemos-* -f
# Logs for a specific service
sudo journalctl -u phonemos-keycloak -f
# Logs since a specific time
sudo journalctl -u phonemos --since "1 hour ago"Docker Container Logs
1
2
3
4
5
6
7
8
# Follow logs for a specific container
docker logs -f hasura
# Last 100 lines
docker logs --tail 100 backend
# With timestamps
docker logs -t frontendNginx Access Logs
Nginx logs to stdout/stderr inside the container, which Docker captures:
1
docker logs -f ingressHow Systemd Services Work
Each systemd unit runs a docker compose up -d command that combines:
Base compose file from /opt/phonemos/<service>/docker-compose.yaml
Overlay file from /etc/phonemos/<service>/overlay.yaml
Environment files from /etc/phonemos/<service>/config (and /opt/phonemos/app/version for the main app)
Example from phonemos.service:
1
2
3
4
5
6
ExecStart=docker compose \
-f /opt/phonemos/app/docker-compose.yaml \
-f /etc/phonemos/app/overlay.yaml \
--env-file=/opt/phonemos/app/version \
--env-file=/etc/phonemos/app/config \
up -dThe RemainAfterExit=yes directive means systemd considers the service active as long as the containers are running, even though the docker compose up -d command itself exits immediately.
Enabling / Disabling Connectors
Connector services are conditionally enabled during scripts/setup-systemd.sh based on the flags in /etc/phonemos/setup.conf:
ENABLE_YOUTRACK=yes -- enables phonemos-connector-youtrack.service
ENABLE_JIRA_DC=yes -- enables phonemos-connector-jira-dc.service
To enable a connector after initial setup:
1
2
3
# Enable and start the YouTrack connector
sudo systemctl enable phonemos-connector-youtrack
sudo systemctl start phonemos-connector-youtrackTo disable a connector:
1
2
sudo systemctl stop phonemos-connector-youtrack
sudo systemctl disable phonemos-connector-youtrackRelated Documentation
Installation -- initial setup
Folder Structure -- where service files and configs are located
Networking -- Docker networks and routing
Troubleshooting -- diagnosing service failures