# gerbeur

A small invite-only social platform for sharing links and files. Users can post URLs and media (YouTube, SoundCloud, Bandcamp, images, …), vote, comment, follow each other, and build playlists. A real-time WebSocket layer handles live presence, vote counts, and notifications.

## Stack

| Layer    | Technology                                        |
| -------- | ------------------------------------------------- |
| Runtime  | [Deno](https://deno.com) 2.x                      |
| API      | [Oak](https://jsr.io/@oak/oak) (HTTP + WebSocket) |
| Database | SQLite via `node:sqlite`                          |
| Frontend | React 19 + Vite 8                                 |

## Development

### Prerequisites

- Deno 2.x

### Setup

```sh
cp .env.example .env
# Edit .env: set GERBEUR_JWT_SECRET to the output of: openssl rand -hex 32
```

### Run

```sh
deno task dev
```

This starts both the API server (port 8000, with file watching) and the Vite dev server (port 3000) concurrently.

Open [http://localhost:3000](http://localhost:3000). On first run a default `admin` / `admin` account is created — change the password immediately.

### Environment variables

See [`.env.example`](.env.example) for the full list with descriptions. Key variables:

| Variable                  | Description                                                                  | Default                 |
| ------------------------- | ---------------------------------------------------------------------------- | ----------------------- |
| `GERBEUR_JWT_SECRET`      | JWT signing secret — **required**, generate with `openssl rand -hex 32`      | —                       |
| `GERBEUR_PORT`            | API server port                                                              | `8000`                  |
| `GERBEUR_ALLOWED_ORIGINS` | Comma-separated list of allowed CORS origins                                 | `http://localhost:3000` |
| `VITE_API_HOSTNAME`       | Override API hostname in the frontend bundle (see [Production](#production)) | unset                   |

## Production

### Docker (recommended)

The standard deployment runs API and frontend in a single container. The API server (Oak) serves the compiled frontend as static files, so both share the same origin — no CORS configuration needed, no `VITE_API_*` build args needed.

```sh
docker build -t gerbeur .

docker run -d \
  -p 8000:8000 \
  -v gerbeur-db:/app/api/sql \
  -v gerbeur-uploads:/app/api/uploads \
  -e GERBEUR_JWT_SECRET=$(openssl rand -hex 32) \
  -e GERBEUR_ALLOWED_ORIGINS=https://example.com \
  -e GERBEUR_PROTOCOL=https \
  -e GERBEUR_HOSTNAME=example.com \
  -e GERBEUR_PORT=8000 \
  --name gerbeur \
  gerbeur
```

The two volumes are required for persistence:
- `gerbeur-db` — SQLite database (`api/sql/gerbeur.db`), initialized automatically on first run
- `gerbeur-uploads` — user-uploaded files (`api/uploads/`)

#### Separate API and frontend (optional)

If you need to run the API on a different host than the frontend, pass the API location as build args so it gets baked into the frontend bundle:

```sh
docker build \
  --build-arg VITE_API_PROTOCOL=https \
  --build-arg VITE_API_HOSTNAME=api.example.com \
  --build-arg VITE_API_PORT=443 \
  -t gerbeur .
```

### Reverse proxy

Put a reverse proxy (nginx, Caddy, …) in front of the container to handle TLS. Forward everything to port 8000. Example Caddyfile:

```
example.com {
    reverse_proxy localhost:8000
}
```

## Project structure

```
api/
  main.ts          # Entry point — Oak application, middleware, routes
  config.ts        # Environment variables
  middleware/      # errorMiddleware, authMiddleware
  routes/          # HTTP routes + WebSocket
  services/        # Business logic
  model/           # Database schema, row types, type guards
  lib/             # JWT, pagination, upload helpers, …
  sql/
    schema.sql     # Database schema
    init.ts        # First-run database initialisation
    gerbeur.db     # SQLite database (not committed)
  uploads/         # User-uploaded files (not committed)
src/               # React frontend (Vite)
  config/api.ts    # API base URL, validation constants
  pages/           # Route-level components
  components/      # Shared UI components
  contexts/        # Auth, WebSocket, player, follows
  hooks/           # Data fetching and UI hooks
public/            # Static assets (favicon, icon sprite)
```