Usage guide

Administration guide

Quickstart

If you’d like to test Convinator before you go on with a more configured setup, you can run this command to get a basic server with the default configuration:

docker run -p "3000:3000" --rm -it codeberg.org/borisnl/convinator:latest

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.

`CONVI_CONFIG_FILE`

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

`CONVI_DATABASE_URL`

Convinator supports postgres, mysql and sqlite databases. This variable should be set to the connection string for the database. For example:

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

Defaults to sqlite://convinator.db?mode=rwc.

Used for encoding authentication JWTs. Generate one using: openssl rand -hex 32. Although this variable is not required, it is HIGHLY recommended to set it. If not, a random string will be generated on every server startup. This means that users will have to reauthenticate every time the server restarts.

`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://garage:3900"
# access_key = ""
# secret_key = ""
region = "garage"
bucket_name = "convinator"

[link_embeds]
enabled = true
allowed_urls = ["https://*"]

`[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"

[link_embeds]
enabled = true
allowed_urls = ["https://*"]

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

Clone the repository

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

Install dependencies using pnpm
```
pnpm install --frozen-lockfile
```

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

Start the development containers:
```
docker compose up -d
```
Setup garage (local S3 service). This command should also update your .env file with the generated secrets.
```
./scripts/setup-garage.sh
```
Run the backend using cargo
```
cargo run
```
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!

Convinator Documentation