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

Keep in mind that when you run this command, you haven’t configured the database or file storage. Sensible defaults will be used, but when this container stops, all data will be deleted. For more information about configurating your instance, check out the configuration page.

Requirements

Instance Setup

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.

`CONVI_JWT_SECRET`

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.

# server_host_url = "https://api.example.com"

[storage]
adapter = "fs"

[storage.fs]
base_dir = "uploads"

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

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

`server_host_url`

Optional url for the location of the server. This is only required if the server is on a different host from where the frontend is served. If not set, Convinator will attempt to use the CONVI_SERVER_HOST_URL environment variable.

For example: if you host the frontend on example.com and the server on api.example.com, you’d have this:

server_host_url = "https://api.example.com"

`[storage]`

Configuration for storing files like message attachments or profile pictures.

`adapter`

Storage adapter identifier. Options: fs, s3.

`[storage.fs]`

File system storage options.

`base_dir`

Location for all stored files.

`[storage.s3]`

S3 specific options.

`endpoint`

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

`access_key`

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

`secret_key`

S3 secret key. If not set, Convinator will attempt to use the CONVI_STORAGE_S3_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_S3_REGION environment variable.

`bucket_name`

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

Storage Example

[storage]
adapter = "fs"

[storage.fs]
base_dir = "uploads"

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

`[link_embeds]`

Configure fetching of metadata from shared urls, and rendering them in a card in the chat.

`enabled`

Boolean to enable or disable embeds. Defaults to enabled (true).

`allowed_urls`

Array of globs which match urls that are fetched and embedded. This feature uses the globset crate and detailed usage can be found there. A good example of a glob that you might want to use is: "https://*" to only match urls that support HTTPS.

Link Embeds Example

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

`[auth]`

Options to configure registration and authentication.

`registration_enabled`

Boolean to enable or disable registration. Defaults to enabled (true).

`registration_token`

Optional token the user must provide to register a new account. If not set, Convinator will attempt to use the CONVI_AUTH_REGISTRATION_TOKEN environment variable. Can be omitted to leave registration open if enabled (not recommended). Useful for when you want to onboard a large number of users.

Auth Example

[auth]
registration_enabled = true
registration_token = "supersecrettoken"

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
```
If you’d like to use the S3 adapter, you need to set up garage (a 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