# How to install and use RtCord

See [API.md](API.md) for the complete HTTP, WebSocket, authentication, and
payload reference.

The frontend is authored in `site/` and built with Jekyll. Run `make` to build
both the static HTML/CSS/JavaScript assets and the Go server binary. The
reStructuredText developer and operator documentation is in `DOCUMENTATION/`
and can be built with `make docs` when Sphinx is installed.

Install the Ruby dependencies before building:

```bash
bundle install
```

## Requirements

- MariaDB or MySQL
- Go 1.26.5 or newer if building from source
- Ruby and Jekyll 4.4 or newer for frontend builds
- Sphinx 8 or newer for the documentation build
- Git, if cloning the repository

## Set up MariaDB

Install MariaDB:

- On Arch Linux:
```bash
sudo pacman -S mariadb
```

Then follow [Arch's MariaDB guide](https://wiki.archlinux.org/title/MariaDB) to initialize, enable, and start the database service.

Create a database and database user. You can use an existing MySQL/MariaDB user instead:

```sql
CREATE DATABASE rtcord CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
CREATE USER 'rtcord'@'localhost' IDENTIFIED BY 'choose-a-password';
GRANT ALL PRIVILEGES ON rtcord.* TO 'rtcord'@'localhost';
FLUSH PRIVILEGES;
```

From the repository root, import the schema:

```bash
mariadb -uYOUR_USER -p YOUR_DATABASE < schema.sql
```

The schema creates the tables only; it does not insert users, servers, messages, or other application data.

## Configure the application

Copy the example environment file:

```bash
cp .env.example .env
```

Edit `.env` to match the database you created:

```dotenv
PORT=8090
DB_USER=rtcord
DB_PASS=choose-a-password
DB_IP=localhost:3306
DB_TABLE=rtcord
```

`DB_IP` is the database host and port, not the application port. `PORT` controls the HTTP server port.

Email verification and password reset require SMTP settings:

```dotenv
APP_URL=https://your-rtcord-domain.example
SMTP_HOST=smtp.protonmail.ch
SMTP_PORT=587
SMTP_USER=your-proton-address@example.com
SMTP_PASS=your-proton-smtp-token
SMTP_FROM=your-proton-address@example.com
```

## Run from source

Download dependencies and build the service:

```bash
go mod download
go build ./...
```

Build the HTML documentation separately:

```bash
make docs
```

Start the server:

```bash
go run .
```

The application listens on:

```text
http://localhost:8090
```

If you configured a different `PORT`, use that port instead.

## Run a pre-built binary

Pre-built binaries are available from the repository's **Releases** tab when a release has been published.

- For AMD64/x86-64, download the x86-64 variant.
- For ARM64, an ARM64 build may not be available yet. Building from source is recommended; [FEX](https://github.com/FEX-Emu/FEX) may also be usable on supported systems.

Keep the `.env` file in the working directory when starting the binary:

```bash
./rtcord-v81
```

## First use

1. Open the application in a browser.
2. Create an account.
3. Log in.
4. Create a server or accept an invite.
5. Use the **Messages** page for direct messages and group chats.

## Existing databases

`schema.sql` is intended for a new, empty database. Do not import it into a database that already contains the RtCord tables unless you intend to recreate the schema.

For an existing installation, apply only the migration needed for the feature being added, in the order documented by that migration. Available migrations include:

- `migration_channels.sql`
- `migration_custom_roles.sql`
- `migration_message_editing.sql`
- `migration_friends.sql`
- `migration_conversations.sql`
- `migration_attachments.sql`
- `migration_reports.sql`
- `migration_message_replies.sql`
- `migration_message_reactions.sql`
- `migration_email_verification.sql`
- `migration_account_admin.sql`

Back up an existing database before applying migrations.

Attachments are stored as files in the repository's `uploads/` directory. The
directory must be writable by the service. Back it up alongside the database if
uploaded files need to be preserved.

## Troubleshooting

- **Connection error:** verify that MariaDB is running and that `DB_USER`, `DB_PASS`, `DB_IP`, and `DB_TABLE` in `.env` are correct.
- **Unknown database:** create the database before importing `schema.sql`.
- **Access denied:** grant the configured user privileges on the configured database.
- **Port already in use:** change `PORT` in `.env`.
- **Page cannot be rendered:** start the service from the repository root so the `public/` templates can be found.