Phonemos User Guide

Single-Server Linux Installation

The easiest way to deploy Phonemos on a single VM or physical server. This setup uses Docker Compose to run Phonemos and all its dependencies as containers on a single Linux host, managed by systemd. Everything is included: the application, a reverse proxy (Nginx), authentication (Keycloak), object storage (MinIO), and the database (PostgreSQL).

Prerequisites

  • A Linux-based system (Ubuntu recommended)

  • Docker (the setup script can install it automatically if not present)

  • At least 100 GB of disk space

  • Root access or sudo privileges

Quick Start

  1. Boot a the virtual machine with the Ubuntu image

  2. Switch to root user

  3. Create and configure a new ssh key using

    1 2 3 4 5 6 7 8 9 10 11 # Generate or copy the deployment key to ~/.ssh/deploy_key ssh-keygen -t ed25519 -C "deploy key" -f ~/.ssh/deploy_key # Add the following to ~/.ssh/config cat >> ~/.ssh/config << EOF Host phonemos-linux HostName github.com User git IdentityFile ~/.ssh/deploy_key IdentitiesOnly yes EOF

  4. Send the public key (~/.ssh/deploy_key.pub) to your Phonemos provider so they can setup your access

  5. Wait until you get the positive confirmation that they have added they key. Otherwise you will not be able to pull the repository in the next step.

  6. Clone the phonemos-linux repository to /opt/phonemos-linux

    1 2 3 sudo mkdir -p /opt/phonemos-linux sudo chown ubuntu /opt/phonemos-linux/ git clone git@phonemos-linux:linkyard/phonemos-linux.git /opt/phonemos-linux

  7. Run sudo ./setup-phonemos.sh in /opt/phonemos-linux

  8. Follow the interactive setup (hostname, TLS, data directory)

  9. Complete the post-install steps (DNS, Keycloak configuration, service startup)

The setup script handles everything automatically: Docker installation, user creation, network setup, certificate configuration, image pulling, and systemd service registration.

More information