From 844fbf7c9e0bbd755cae6cd6a0c6f027c3f7978d Mon Sep 17 00:00:00 2001 From: Jesse Wierzbinski Date: Tue, 1 Apr 2025 13:52:47 +0200 Subject: [PATCH] docs: :memo: Update installation documentation to match latest guidelines --- docs/.vitepress/config.ts | 13 ++----- docs/cli/index.md | 2 +- docs/setup/database.md | 7 ---- docs/setup/installation.md | 72 ++++++++++++++++++++++++++++++-------- 4 files changed, 60 insertions(+), 34 deletions(-) delete mode 100644 docs/setup/database.md diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts index 3e580b25..01920f50 100644 --- a/docs/.vitepress/config.ts +++ b/docs/.vitepress/config.ts @@ -35,17 +35,8 @@ export default defineConfig({ sidebar: [ { - text: "Setup", - items: [ - { - text: "Installation", - link: "/setup/installation", - }, - { - text: "Database", - link: "/setup/database", - }, - ], + text: "Installation", + link: "/setup/installation", }, { text: "CLI", diff --git a/docs/cli/index.md b/docs/cli/index.md index 3851b3c7..67ec35a2 100644 --- a/docs/cli/index.md +++ b/docs/cli/index.md @@ -9,7 +9,7 @@ Versia Server includes a built-in CLI for managing the server. To use it, simply ```bash # Docker # Replace `versia` with the name of your container -docker compose exec -it versia /bin/sh /app/entrypoint.sh cli help +docker compose exec -it versia sh /app/entrypoint.sh cli help ``` You can use the `help` command to see a list of available commands. These include creating users, deleting users and more. Each command also has a `--help,-h` flag that you can use to see more information about the command. diff --git a/docs/setup/database.md b/docs/setup/database.md deleted file mode 100644 index dc98cd6f..00000000 --- a/docs/setup/database.md +++ /dev/null @@ -1,7 +0,0 @@ -# Installing the database - -Versia Server uses a special PostgreSQL extension called `pg_uuidv7` to generate UUIDs. This extension is required for Versia Server to work properly. To install it, you can either use the pre-made Docker image or install it manually. - -## Using the Docker image - -Versia Server offers a pre-made Docker image for PostgreSQL with the extension already installed. Use `ghcr.io/versia-pub/postgres:main` as your Docker image name to use it. \ No newline at end of file diff --git a/docs/setup/installation.md b/docs/setup/installation.md index e96dcfc0..8fffb339 100644 --- a/docs/setup/installation.md +++ b/docs/setup/installation.md @@ -2,39 +2,43 @@ ## Requirements -- A Linux-based operating system. Kernel version `6.1` or later is recommended. -- Basic knowledge of Docker and Docker Compose. +- 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 -> [!INFO] -> -> Traditional "from-source" installation is not supported, as the server is designed to be run in a containerized environment. This guide will cover how to run the server using Docker. -> -> You may still run the server without Docker, but I can't guarantee that it will work properly. - 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. Make sure to use the config template from the same branch as the server. +> 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 -curl -o docker-compose.yml https://raw.githubusercontent.com/versia-pub/server/v0.7.0/docker-compose.yml +# 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 set up the database connection and other settings -2. Download the `config.example.toml` file from the repository + +2. Edit the `docker-compose.yml` file to your liking, e.g removing the `db` service if you want to use an existing database. + +3. Download the `config.example.toml` file from the repository ```bash -curl -o config.example.toml https://raw.githubusercontent.com/versia-pub/server/v0.7.0/config/config.example.toml +# 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 ``` -4. Edit the `config.example.toml` file to set up the database connection and other settings, rename it to `config.toml`, then place it inside `config/` (create the `config/` directory if it does not exist) -5. Run the following command to start the server: + +4. 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. +5. Run the following command to start the server: + ```bash docker compose up ``` @@ -43,6 +47,44 @@ 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.