Usage guide

Administration guide

Requirements

TODO: User skills (docker etc)

TODO: Minimum system requirements

Instance Setup

TODO: Docker config example

TODO: Link to config docs

TODO: Link to /environments/development in the repo for an example

Configuration

Convinator uses a two part configuration system: environment variables for sensitive secrets, and a TOML config file for less sensitive variables.

Environment Variables

All Convinator environment variables start with CONVI_. This section only includes variables that are not documented elsewhere. Required environment variables are marked with an asterisk (*).

CONVI_CONFIG_FILE

Location for the convinator.toml file. Defaults to ./convinator.toml.

CONVI_DATABASE_URL*

Connection string for the database. For example:

• postgres://convinator:supersecretpassword@localhost:5342/convinator
• sqlite://db.sqlite?mode=rwc

CONVI_JWT_SECRET*

Should be set to a random secret string. Used for encoding authentication JWTs. Generate one using: openssl rand -hex 32

convinator.toml

This TOML file is used to configure Convinator.

Complete Example

If you just want to quickly set up your instance, copying this config should get you a long way. You can find more about each configuration option below.

[storage]
endpoint = "http://localhost:3900"
# access_key = ""
# secret_key = ""
region = "garage"
bucket_name = "convinator"

[storage]

Configuration for S3 compatible storage. Used for uploading files, like message attachments or profile pictures.

endpoint

Endpoint for your S3 provider. If not set, Convinator will attempt to use the CONVI_STORAGE_ENDPOINT environment variable.

access_key

S3 access key. If not set, Convinator will attempt to use the CONVI_STORAGE_ACCESS_KEY environment variable.

secret_key

S3 secret key. If not set, Convinator will attempt to use the CONVI_STORAGE_SECRET_KEY environment variable.

region

Bucket region. If using garage this should be garage. If not set, Convinator will attempt to use the CONVI_STORAGE_REGION environment variable.

bucket_name

Bucket name, defaults to convinator. If not set, Convinator will attempt to use the CONVI_STORAGE_BUCKET environment variable.

Storage Example

[storage]
endpoint = "http://localhost:3900"
access_key = "GKf82ad4401d11c2d15a95646d"
secret_key = "0330fa367bfc497f054071a5700f57874f02b0958f831710f9be2132b4d9075f"
region = "garage"
bucket_name = "convinator"

Development guide

This section of the documentation is aimed at developers who’d like to contribute to Convinator. If you are only interested in running your own instance, check out the Admin guide instead.

Environment Setup

0. Clone the repository

   git clone ssh://git@codeberg.org/borisnl/Convinator.git convinator && \
   cd convinator
   

1. Install dependencies using pnpm

   pnpm install --frozen-lockfile
   

2. Copy the .env.example file to .env and set the CONVI_JWT_SECRET to a random string

   cp .env.example .env && \
   sed -i "s/^CONVI_JWT_SECRET=.*$/CONVI_JWT_SECRET=$(openssl rand -hex 32)/g" .env
   

3. Start the development containers:

   docker compose up -d
   

4. Setup garage (local S3 service). This command should also update your .env file with the generated secrets.

   ./scripts/setup-garage.sh
   

5. Run the backend using cargo

   cargo run
   

6. Run the frontend (in a new terminal)

   cd packages/convi-web && pnpm start
   

You should now be able to reach the frontend at localhost:4200 and start making changes!

Contributing Guidelines