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
├── minio/
│   └── docker-compose.yaml    # MinIO 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
│       ├── minio.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)
├── minio/
│   ├── config                 # MinIO 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
└── minio/                     # MinIO object storage files

These directories are bind-mounted into containers through the overlay YAML files. They are owned by the phonemos system user.

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-minio.service	MinIO 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