Archivum/README.md

# Archivum

Archivum är ett självhostat wiki- och dokumenthanteringssystem. Det är tänkt att användas för allt från enkla anteckningar och teknisk dokumentation till världsbyggande inför rollspelskampanjer. Alla dokument lagras som **AsciiDoc**-filer (`.adoc`) på disk, vilket innebär att du kan läsa och redigera dem direkt med valfritt predikat — utan att öppna webbgränssnittet. Applikationen renderar dokumenten till HTML i webbläsaren och hanterar automatisk **versionshantering via Git**, så att varje sparning skapar ett commit och alla ändringar kan rullas tillbaka.

> Se [ARCHITECTURE.md](ARCHITECTURE.md) för detaljerad dokumentation om arkitektur, exekveringsflöden och komponentstruktur.

---

## Användningsområden

- **Anteckningar** — snabbanteckningar och personliga kunskapsbaser
- **Wiki** — team-wiki med dokumentträd och historik
- **Teknisk dokumentation** — API-dokumentation, systembeskrivningar, runbooks
- **Rollspelskampanjer** — världsbyggande, NPC-register, kartor och händelseloggar

---

## Krav

### För att köra med Docker (rekommenderat)

- [Docker](https://docs.docker.com/get-docker/) ≥ 24
- [Docker Compose](https://docs.docker.com/compose/) v2

### För lokal utveckling

- [Go](https://go.dev/dl/) ≥ 1.22
- [Node.js](https://nodejs.org/) ≥ 20 + npm
- [Git](https://git-scm.com/) (används av backenden för versionshantering)

---

## Snabbstart med Docker Compose

### Alternativ A — Hämta image från privat registry (rekommenderat)

Det enklaste sättet att köra Archivum är att hämta en färdigbyggd image från ett privat registry, utan att behöva källkoden.

**1. Logga in mot ditt registry (om det kräver autentisering):**

```bash
docker login ditt-registry.example.com
```

**2. Skapa en `docker-compose.yml`:**

```yaml
services:
  archivum:
    image: ditt-registry.example.com/archivum:latest
    container_name: archivum
    restart: unless-stopped
    ports:
      - "${HOST_PORT:-8080}:4000"
    environment:
      DOCKER_PATH: /config
      UI_DIR: /srv/archivum/ui
      PUID: ${PUID:-1000}
      PGID: ${PGID:-1000}
      TZ: ${TZ:-Europe/Stockholm}
    volumes:
      - ${DOCKER_PATH:-./local}/config:/config
      - ${DOCKER_PATH:-./local}/data:/data
    networks:
      - archivum-net

networks:
  archivum-net:
    driver: bridge
```

> Om du kör en **reverse proxy** (t.ex. Nginx Proxy Manager eller Traefik) i en separat compose-stack kan du låta dem dela nätverk istället för att exponera porten direkt. Deklarera då det externa nätverket:
>
> ```yaml
> networks:
>   proxy-net:
>     external: true
> ```
>
> Och byt ut `archivum-net` mot `proxy-net` i service-definitionen. Ta även bort `ports`-sektionen om proxyn hanterar all trafik.

**3. Skapa en `.env`-fil i samma katalog som `docker-compose.yml`:**

```env
# Sökväg på hosten där config/ och data/ skapas
DOCKER_PATH=/opt/archivum

# Port som exponeras på hosten
HOST_PORT=8080

# Kör containern som denna användare/grupp (kör `id` för att se dina värden)
PUID=1000
PGID=1000

# Tidszon
TZ=Europe/Stockholm
```

**4. Starta:**

```bash
docker compose up -d
```

**5. Öppna** `http://localhost:8080` i webbläsaren. Installationsguiden startar automatiskt vid första körningen.

---

### Alternativ B — Bygg imagen lokalt från källkod

Klona repot och använd den medföljande compose-filen som också bygger imagen:

```bash
docker compose -f docker/docker-compose.yml up -d --build
```

---

## Lokal utveckling

### Backend

```bash
cd backend
go run ./cmd/server
# Servern lyssnar på :4000
# config.json i backend/ används som konfiguration
```

### Frontend

```bash
cd frontend
npm install
npm run dev
# Dev-server på :5173 med proxy till :4000
```

Öppna `http://localhost:5173`. API-anrop proxyas automatiskt till backend-servern.

### Bygga frontend för produktion

```bash
cd frontend
npm run build
# Utdata i frontend/dist/
```

---

## Konfiguration

Konfigurationen lagras i `config.json`. Filen skapas automatiskt av installationsguiden. 

| Fält           | Beskrivning                                         |
|----------------|-----------------------------------------------------|
| `storage_path` | Sökväg till katalogen där .adoc-filer och Git-repot lagras |
| `db_path`      | Sökväg till SQLite-databasen (användarkonton)       |
| `jwt_secret`   | Hemlig nyckel för session-tokens                    |
| `listen_addr`  | TCP-adress att lyssna på, t.ex. `:4000`             |
| `ldap`         | Valfri LDAP-konfiguration för företagsinloggning    |

---

## Autentisering & behörigheter

Archivum stöder tre inloggningssätt:

- **SSO via Authentik (OIDC)** — rekommenderat. Användare loggar in genom
  Authentik (som i sin tur autentiserar mot LDAP). Grupp-medlemskap avgör roll
  och åtkomst. Se [`docs/AUTHENTIK_SETUP.md`](docs/AUTHENTIK_SETUP.md).
- **Lokala konton** — skapas i setup-guiden och i admin-panelen (bcrypt).
- **Publik användare** — anonym, väljs på login-sidan; ser bara det admin delat.

**Roller:** medlemmar i gruppen `Archivum-admin` är administratörer (ser/gör allt,
administrerar sidan). Alla andra styrs av åtkomstreglerna.

**Åtkomstmodell:** per sökväg (dokument eller mapp) tilldelar admin `allow`/`deny`
till användare och grupper. Standard är **deny**; en `allow` ger tillgång, en
`deny` vinner alltid. Reglerna kombineras över användarens alla grupper och
överliggande mappar. Hanteras under **Admin Settings → Access Control**.

## Automatiskt bygge (Gitea Actions)

Vid push till `main` bygger den självhostade Gitea-runnern (arm64, på Pi5)
imagen och pushar den till registryn:

```
localhost:5000/archivum:latest
localhost:5000/archivum:<commit-sha>
```

Workflow: [`.gitea/workflows/build.yaml`](.gitea/workflows/build.yaml). Deploya
sedan `localhost:5000/archivum:latest` från din compose-stack på Pi5.

## Dokumentformat

Alla dokument skrivs i [AsciiDoc](https://asciidoc.org/). Exempeldokument:

```asciidoc
= Mitt dokument
:author: Anna Andersson
:date: 2026-04-12

== Introduktion

Det här är ett *fetstilt* stycke med en https://example.com[länk].

== Kodexempel

[source,go]
----
fmt.Println("Hello, Archivum!")
----
```

Filen sparas som `mitt-dokument.adoc` i `storage_path` och versionshanteras automatiskt.

---

## Docker: Multi-arch build

För att bygga och pusha en image som stöder både AMD64 och ARM64 (Raspberry Pi):

```bash
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t ditt-registry/archivum:latest \
  -f docker/Dockerfile --push .
```