Versia Server Docs

Appearance

Installation ​

Requirements ​

  • A Linux-based operating system. Kernel version 6.1 or later is recommended.
  • Basic knowledge of Docker and Docker Compose.

Traditional "from-source" installation is not supported, as this software is designed to be run in a containerized environment. This guide will cover how to run the server using Docker.

Installation ​

  1. Download the docker-compose.yml file from the repository

NOTE

You may need to change the image from ghcr.io/versia-pub/server:latest to ghcr.io/versia-pub/server:main if you want to use the latest changes from the main branch.

bash
# Set this to "main" for the development build
TAG=v0.7.0
curl -o docker-compose.yml https://raw.githubusercontent.com/versia-pub/server/$TAG/docker-compose.yml

  1. Edit the docker-compose.yml file to your liking, e.g removing the db service if you want to use an existing database.

  2. Download the config.example.toml file from the repository

bash
# This should be the same as the TAG variable above
TAG=v0.7.0
curl -o config.example.toml https://raw.githubusercontent.com/versia-pub/server/$TAG/config/config.example.toml
  1. Edit the config.example.toml to your liking. You will at least need to change the postgres, redis and http sections to match your environment.

WARNING

The first time you start the server, it will complain about missing keys in the configuration file.

These will be autogenerated and printed to the console, so you can copy them to your config.toml file.

  1. Run the following command to start the server:
bash
docker compose up

You may need root privileges to run Docker commands.

To check server logs, run docker compose logs versia. The server will likely stop if there is an error, so you can check the logs to see what went wrong.

Installing the frontend ​

The frontend is not included in the Docker image, so you will need to install it separately.

To do this, you may copy the static files from our frontend's Docker image:

bash
# The frontend does not have a stable tag, so we use the main branch
TAG=main
OUTDIR=./frontend
TEMP=$(sudo docker create ghcr.io/versia-pub/frontend:$TAG)
sudo docker cp $TEMP:/app/public $OUTDIR
sudo docker rm $TEMP

TIP

This command can be re-run to update the frontend to the latest version.

Then, set the following bind mount in your docker-compose.yml file:

yaml
services:
    versia:
        ...
        volumes:
            # If you set OUTDIR to a different directory, change this to match
            # e.g. - ./custom-frontend:/frontend
            - ./frontend:/frontend

Finally, update the config to point to the frontend:

toml
[frontend]
path = "/frontend"

Running the Server ​

Database migrations are run automatically on startup.

Please see the CLI documentation for more information on how to use the CLI.

Updating the server ​

Updating the server is as simple as running docker-compose pull to update the Docker images, then docker-compose up to restart the server.

Sometimes, new configuration options are added to config.example.toml. If you see a new option in the example file, you should add it to your config.toml file.