User guide

Welcome to Convinator! This section of the documentation covers everything you need to know about using Convinator.

Channels

Messaging

Convinator supports a subset of markdown in messages. Supported options are:

Text headings:
Add hashes (#) before a sentence to make the text a heading. Smallest heading is h4.
```
# Large heading

## Smaller heading

### Even smaller heading

#### Smallest heading
```
Bold text:
To make text bold, surround it with double asterisks (*)
```
I am **bold**!
```
Italic text:
To make text italic, surround it with single asterisks (*)
```
This text is _italic_!
```
Code:
Wrap your line with backticks (`) to mark it as code.
```
Take a look at this: `println!("hello world");`
```
Or if you have multiple lines, use a fenced code block:
```
```rs
fn main() {
    println!("hello world!")
}
```
```
Links:
To add links, you can simply paste them in your message. But if you’d like to change the content of the link without changing the actual destination, you can use this syntax:
```
[link content](https://www.example.com)
```
Strike through:
Wrap your text in tildes (~) to put a line through it:
```
~An untrue statement~
```

Lists:
There’s three types of lists: ordered, bulleted, and task:

1. Ordered
2. list
3. example

- Bulleted
- list
- example

- [x] Task
- [ ] list
- [ ] example

Roles

Admin guide

This part of the documentation is about how to set up and run a Convinator instance.

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

Convinator is made to be as simple to use as possible, and optimized for performance. It is tested to run on devices with very little resources. To run Convinator, it is recommended to have some experience with the terminal and Docker.

System requirements

There are no minimal system requirements to run Convinator. However, lower-end devices will result in worse performance. While this is generally not really noticeable, it might become an issue when running for many users¹.

If you run an instance, please let us know your server specs and user count so we can update this page with more accurate measurements. ↩

Instance Setup

There are a few ways to set up a Convinator instance, but by far the easiest method is to use docker-compose.

Docker compose setup

For this setup, you need to create 3 files: a docker compose file, environment file, and Convinator configuration.

# ./docker-compose.yml
name: convinator

volumes:
  pg_data:

services:
  database:
    image: postgres:18
    restart: unless-stopped
    shm_size: 128mb
    environment:
      POSTGRES_DB: 'convinator'
      POSTGRES_USER: 'convinator'
      POSTGRES_PASSWORD: '${DATABASE_PASSWORD}'
      TZ: utc
    volumes:
      - pg_data:/var/lib/postgresql
    healthcheck:
      test: ['CMD-SHELL', 'pg_isready', '-U', 'convinator', '-d', 'convinator']
      interval: 30s
      timeout: 60s
      retries: 5
      start_period: 80s

  convinator:
    image: codeberg.org/borisnl/convinator
    restart: unless-stopped
    ports:
      - '3000:3000'
    volumes:
      - ./convinator.toml:/data/convinator.toml:ro
      - ./uploads:/data/uploads
    env_file: .env
    depends_on:
      database:
        condition: service_healthy

For the environment file, you need to generate 2 secrets: database password, and JWT secret. You can do this using the terminal like this:

openssl rand -hex 32

# ./.env
DATABASE_PASSWORD=your-generated-secret
CONVI_JWT_SECRET=other-generated-secret
CONVI_DATABASE_URL="postgres://convinator:${DATABASE_PASSWORD}@database:5342/convinator"

Finally the Convinator configuration. For more info on this file, see the configuration docs.

# ./convinator.toml
[storage]
adapter = "fs"

[storage.fs]
base_dir = "uploads"

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

After creating these files, you are ready to start the instance!

docker compose up -d

Now your instance should be running on localhost:3000.

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"
# cors_origins = ["http://localhost:4200"]

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

`cors_origins`

Control the access-control-allow-origin header for increased security. Highly recommended to set this variable to the place where your frontend is served. If not set Convinator will default it to *, making your deployment less secure.

cors_origins = ["https://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 administration guide instead.

Environment Setup

Requirements

To develop Convinator, there are some software requirements you need to have installed:

docker
- Runs the database and other services in containers
rust
- Primary backend language
node
- Runtime for the frontend
pnpm
- Package manager for frontend dependencies
just
- Command runner for project scripts
tmux
- Terminal multiplexer for running multiple apps at once

Setup

Clone the repository

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

Install the pnpm and cargo dependencies using just
```
just install
```

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

Run the front- and backend in tmux using just
```
just run
```
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.
```
just setup-garage
```

You should now be able to reach the frontend at localhost:4200 and start making changes. Changes in the frontend will automatically reload, but the backend will not. You will have to manually restart it using just run-backend in the backend tmux session (the left pane).

To stop the development server, you can run just kill. This command will kill the tmux session and stop the running docker containers.

Contributing Guidelines

AI (LLM) Policy

Convinator does not condone any use of LLMs. Because of the environmental concerns, legal issues, and codeberg (our git host) policy, all contributions that are made or assisted by LLMs are forbidden.

Don’t force LLM output upon others
If you’re not fluent in English, avoid use of translation tools and use your own language instead. That way, the reader can decide for themselves how to translate your words.

When providing snippets in issues or pull requests, incomplete handwritten code more useful than code that is generated and incorrect.

Keyboard shortcuts

Convinator Documentation