Project Installation & Setup

This page provides setup guides that cover the basic service installation and setup, as well as separate setup guides for the optional observability and database migrations features.

Basic installation requires PostgreSQL for data persistence because it’s the only SeaORM-compatible database with the ability to handle vectorized data types. The only current installation option is to build from source, so you also need the Rust toolchain to build the project.

DocServe optionally supports observability via the OpenTelemetry protocol. The current service design is configured for the SigNoz front end. You can also optionally manage database migrations via the SeaORM CLI for additional localized dev work.

Basic Installation Guide

This guide shows you how to set up the service with the bare minimum configuration, using a Docker image for data persistence layer. All you need for this guide is a Docker setup and the Rust toolchain. More information about setting up telemetry and database migrations is provided in later sections.

Clone the repo and cd into the new project directory

git clone git@github.com:p5chmitz/api-doc.git <project_name>

Bootstrap the Docker environment:

2a. Check for existing Postgres instances that may block PostgreSQL’s default listening port 5432
```
nc -zv 127.0.0.1 5432
```
or
```
sudo lsof -i :5432
```
2b. Check the docker-compose.yml file and edit as desired, including the listening port for the instance; For example, if you already have a PostgreSQL instance listening on port 5432 you can specify a new port with something like the following:
```
ports:
    - '5433:5432'
```
2c. Run docker-compose up -d from the same directory as the docker-compose.yml file
Create the database:

3a. Fetch the container ID
```
docker ps
```
3b. Access the container in interactive mode using the username specified in the docker-compose.yml file; Note that you only need the -h option if you’re connecting to a remote host
```
docker exec -it <container_id> psql -U <username> -h 127.0.0.1
```
3c. Create a new database with UTF8 encoding by running the following command; This example creates a database named apidoc
```
create database apidoc encoding 'utf8';
```
Check the .env file to ensure environment variables match any changes made during database creation/setup; This includes database username, password, non-standard port, and database name
Run cargo run check; This may take some time for the first run because Cargo needs to download dependencies and build the project; The check command automatically checks for pending migrations and applies them; The service ships with only one migration file by default which configures the database with all required tables; You can move on to user creation and general service administration when both the database connection and migrations checks pass

Configuration Sources

The service looks for both configuration and environment files at startup. Configuration files are handy for setting common service configurations across multiple environments, and environment variables are good for either environment-specific values or sensitive information.

The service requires a valid JSON file for operation. By default the service looks for a config.json in the working directory. You can optionally supply a global command, called an “option” in clap, with -c/--config and the path to your desired configuration file. If you prefer to stash all information in a /.env file, such as common with some Kubernetes deployments, you can simply leave the config.json file in the working directory as-is with an empty object ({}) for its contents.

By default the DocServe repo puts all values in the /.env file. This example illustrates a simple set of values. Environment variables must use the DOC__ prefix.

DOC__LOGGING__LOG_LEVEL="INFO"
DOC__DATABASE__URL=postgresql://user:password@localhost:5432/database_name
DOC__TOKEN_SECRET="super secret string"
DOC__TOKEN_TIMEOUT_SECONDS=3600

This example config.json file contains a similar set of information minus potentially sensitive values.

{
   "logging": {
      "log_level": "INFO"
   },
   "token_timeout": 3600
}

Observability

DocServe ships with optional observability functionality via OpenTelemetry protocol (OTLP). By default the service outputs logs to console, but by installing SigNoz you can easily set the service up for much more robust monitoring. There are many ways to install SigNoz, but the easiest method is to clone the repo and run the installer script.

From the desired working directory, clone the repo and cd into the /deploy directory
```
git clone -b main https://github.com/SigNoz/signoz.git && cd signoz/deploy/
```
Run the installer script
```
./install.sh
```
Access the new admin UI via http://localhost:8080/ and set up a new SigNoz account (free)
Add the OTLP endpoint to the DocServe /.env file and fire up the server; By default, SigNoz uses port 4317 to listen for OTLP signals
```
DOC__TRACING__OTLP_ENDPOINT="http://localhost:4317"
```

Database Migrations

DocServe ships with optional data migrations functionality via the SeaORM project. You can install the SeaORM CLI by simply executing the following Cargo command:

cargo install sea-orm-cli

See the service administration page for more information on handling migrations.