Skip to content

Server App Overview

The newguy103-syncserver API docs are already generated by FastAPI's automatic API documentation, so this page will only define a general overview of the FastAPI app.

You can find the generated docs under /docs (Comes from FastAPI).

Server requirements

The app requires these components to function:

  • Python 3.12+ in a virtual environment with uv.
  • A PostgreSQL instance.
  • A Valkey instance.

Running the server

The server can be ran in two ways:

  1. Through the Docker images.
  2. Through cloning the repository locally.

1. Docker

You can pull the image and run the Docker image:

docker pull ghcr.io/newguy103/syncserver:latest
docker run \
--volume ./syncserver_data:/app/syncserver \
--publish 8000:8000
ghcr.io/newguy103/syncserver:latest

There is a Docker Compose example in the docker directory of the repository if you prefer using compose.

You can also use the edge tag for the images built per commit in the main branch.

2. Cloning the repository

You can clone the repository and run it directly:

git clone https://github.com/newguy103/syncserver
cd syncserver
uv venv
source .venv/bin/activate
uv sync

Running the server is simple:

fastapi run app/server/main.py

This will start the app and expose it under http://0.0.0.0:8000

Environment variables

newguy103-syncserver requires some environment variables to run properly. These use pydantic-settings, so putting an .env file in the current directory is supported.

Required variables:

  • POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, POSTGRES_DB and POSTGRES_PASSWORD for the database connection.
  • VALKEY_URI as the URI to the Valkey server.

POSTGRES_PASSWORD raises an error and prevents app startup if the value is still the default helloworld.

Optional variables:

  • ENVIRONMENT=[local | dev | prod]: Sets the environment where the server runs in, defaults to local.
  • USE_VALKEY_CACHE=true: Sets a flag to tell the database to use the Valkey cache. Required to be true if the environment is not local. Used by tests to disable Valkey.
  • DATA_DIRECTORY=./syncserver: The path to the data directory to store files and config. The Docker image keeps this as /app/syncserver, so it's intended to be used when not using Docker.
  • FIRST_USER_NAME=admin: Sets the first user name which will be the superuser.
  • FIRST_USER_PASSWORD=helloworld: Sets the password of the superuser. Raises an error and prevents app startup if the value is still the default in non-local environments.

Authentication

All API requests require authorization, and follows the OAuth2 specification. Tests

There are tests available which are all integration tests for the database and the full route. These tests are in the tests directory.

To run it, clone the repository and install dev dependencies:

uv sync --dev ./scripts/tests.sh

This will run the tests and have the directory and database set to a test directory and temporary sqlite3 database. Or an X-Api-Key header for API key authorization.

Tests

There are tests available which are all integration tests for the database and the full route. These tests are in the tests directory.

To run it, clone the repository and install dev dependencies:

uv sync --dev
./scripts/tests.sh

This will run the tests and have the directory and database set to a test directory and temporary sqlite3 database.