Folder Structure

Overview

A Phonemos installation spans four main locations on the filesystem:

Path	Purpose
/opt/phonemos-linux/	Git repository with scripts, templates, and docker-compose files
/opt/phonemos/	Symlink to opt/phonemos inside the repository; runtime docker-compose root
/etc/phonemos/	Generated configuration files (git-versioned separately)
/data/volumes/	Persistent data (configurable during setup)

Repository Root — /opt/phonemos-linux/

Source for the installation.

/opt/phonemos-linux/
├── setup-phonemos.sh          # Main installation script
├── update-phonemos.sh         # Update / upgrade script
├── README.md
├── MANUAL-STEPS.md            # Version-specific manual upgrade steps
├── doc/                       # Documentation
├── scripts/                   # Modular setup scripts
│   ├── lib.sh                 # Shared functions and variables
│   ├── ask-config.sh          # Interactive configuration collection
│   ├── initialize-config.sh   # Template processing and secret generation
│   ├── install-docker.sh      # Docker installation (Debian/Ubuntu)
│   ├── setup-user.sh          # phonemos system user creation
│   ├── setup-docker.sh        # Docker networks and registry auth
│   ├── setup-data.sh          # Data directories and symlink
│   ├── setup-certificates.sh  # TLS certificate setup
│   ├── setup-systemd.sh       # systemd unit installation
│   ├── setup-git.sh           # Git init for /etc/phonemos/
│   ├── pull-images.sh         # Docker image pull
│   └── next-steps.sh          # Post-install automation
├── etc/
│   ├── phonemos/              # Configuration templates (*.template)
│   └── systemd/system/        # systemd service unit files
└── opt/
    └── phonemos/              # Docker-compose files per service (symlink target)

Runtime Docker-Compose Root — /opt/phonemos/

Created by scripts/setup-data.sh as a symlink: /opt/phonemos → /opt/phonemos-linux/opt/phonemos

Each subdirectory contains a docker-compose.yaml for one service group:

/opt/phonemos/
├── app/
│   ├── docker-compose.yaml    # hasura, backend, backend-pdf, frontend,
│   │                          # redis, confluence-converter, converters
│   ├── version                # PHONEMOS_VERSION and CONTAINER_REGISTRY
│   ├── backend-application.conf
│   ├── pandoc-application.conf
│   └── redis.conf
├── postgres/
│   ├── docker-compose.yaml    # PostgreSQL 17 with pgvector
│   └── init-databases.sh      # Database initialization
├── keycloak/
│   ├── docker-compose.yaml    # Keycloak + Keycloak-Postgres
│   ├── init-databases.sh
│   └── keycloak/
│       └── realm-export.json  # Default realm for import
├── rustfs/
│   └── docker-compose.yaml    # RustFS object storage + bucket init
├── ingress/
│   ├── docker-compose.yaml    # Nginx reverse proxy
│   ├── nginx.conf             # Main nginx configuration
│   └── nginx.conf.d/          # Location routing files
│       ├── phonemos.conf      # TLS server block
│       ├── phonemos.loc       # App routing (frontend, hasura, backend, pdf)
│       ├── keycloak.loc       # /auth routing
│       ├── rustfs.loc         # /phonemos-files* routing
│       └── scim.loc           # /_api/scim routing
└── connector/
    ├── youtrack/
    │   └── docker-compose.yaml
    └── jira-dc/
        └── docker-compose.yaml

Configuration — /etc/phonemos/

Generated during setup from the template files in the repository. This directory is initialized as a git repository to track configuration changes.

/etc/phonemos/
├── setup.conf                 # Main setup configuration (hostname, data dir, TLS, connectors)
├── updates.txt                # Log of applied updates
├── phonemos-cacerts           # Java keystore (self-signed TLS only)
├── app/
│   ├── config                 # Environment variables for the main application stack
│   ├── application.conf       # Custom application settings
│   └── overlay.yaml           # Docker-compose overlay for the app service
├── postgres/
│   ├── config                 # PostgreSQL password
│   └── overlay.yaml           # Overlay (bind-mount for data)
├── keycloak/
│   ├── config                 # Keycloak admin credentials and DB config
│   └── overlay.yaml           # Overlay (bind-mount for data)
├── rustfs/
│   ├── config                 # RustFS root credentials
│   └── overlay.yaml           # Overlay (bind-mount for data)
├── ingress/
│   ├── routes.conf            # Nginx location includes
│   ├── servers.conf           # Additional nginx server blocks
│   ├── overlay.yaml           # Overlay for ingress
│   └── certs/
│       ├── cert.crt           # TLS certificate
│       └── cert.key           # TLS private key
└── connector/
    ├── youtrack/
    │   └── overlay.yaml
    └── jira-dc/
        └── overlay.yaml

Overlay Files

Each service has an overlay.yaml file that is passed as a second -f argument to docker compose. Overlays are used to:

Bind-mount host data directories into containers (e.g. PostgreSQL data from /data/volumes/).
Mount CA certificates for self-signed TLS setups.
Override environment variables or add extra configuration.

These files can be customized after installation.

Data Volumes — /data/volumes/

The data directory (configurable via DATA_DIR in setup.conf, defaults to /data/volumes) holds persistent data:

/data/volumes/
├── phonemos/
│   └── postgres/              # PostgreSQL database files
├── keycloak/                  # Keycloak PostgreSQL database files
└── rustfs/                    # RustFS object storage files

These directories are bind-mounted into containers through the overlay YAML files. PostgreSQL and Keycloak data are owned by the phonemos system user. The RustFS data directory is owned by uid 10001.

Systemd Service Units

Located in the repository at etc/systemd/system/ and copied to /etc/systemd/system/ during setup:

File	Service
phonemos.service	Main application stack (hasura, backend, frontend, redis, converters)
phonemos-postgres.service	PostgreSQL database
phonemos-keycloak.service	Keycloak authentication (+ keycloak-postgres)
phonemos-rustfs.service	RustFS object storage
phonemos-ingress.service	Nginx reverse proxy
phonemos-connector-youtrack.service	YouTrack connector (optional)
phonemos-connector-jira-dc.service	Jira DC connector (optional)

All services run as the phonemos user, depend on docker.service, and use RemainAfterExit=yes so that systemd considers them active while Docker containers are running.

Each service unit combines a base docker-compose.yaml from /opt/phonemos/, an overlay from /etc/phonemos/, and one or more --env-file arguments for configuration.

Phonemos User Guide

Folder Structure