FossilRepo is a Django web application that wraps Fossil SCM repositories with a modern UI. It reads `.fossil` files directly as SQLite databases for speed, and uses the `fossil` CLI binary for write operations to maintain artifact integrity.
6
7
```
8
Browser (HTMX + Alpine.js + Tailwind CSS)
9
|
10
v
11
Django 5 (views, ORM, permissions)
12
|
13
|-- FossilReader (direct SQLite reads, ?mode=ro)
14
|-- FossilCLI (subprocess for writes: commit, ticket, wiki, push/pull)
.fossil files (SQLite: code + wiki + tickets + forum + technotes)
23
|
24
v
25
Litestream --> S3 (continuous SQLite replication)
26
```
27
28
## Core Components
29
30
### FossilReader
31
32
Opens `.fossil` repository files directly as read-only SQLite databases. No network calls to a running Fossil server. Python's `sqlite3` module with `?mode=ro` URI.
33
34
Handles:
35
- Blob decompression (zlib with 4-byte size prefix)
Django handles authentication and access control. Public repos allow anonymous pull (no `--localauth`). Authenticated users with write access get full push via `--localauth`. Branch protection rules are enforced at this layer.
63
64
### SSH Sync
65
66
An `sshd` instance runs on port 2222 with a restricted `fossil-shell` forced command. Users upload SSH public keys via their profile. The `authorized_keys` file is regenerated from the database on key add/remove.
- Soft deletes only: `obj.soft_delete(user=request.user)`, never `.delete()`
84
- `ActiveManager` on `objects` excludes soft-deleted; `all_objects` includes them
85
86
### Permission Model
87
88
Two layers:
89
1. **Org-level roles** (Admin/Manager/Developer/Viewer) — Django Groups with permission bundles, assignable per user
90
2. **Project-level RBAC** (read/write/admin) — per team, via ProjectTeam model
91
92
Project visibility:
93
- **Public** — anyone can read (including anonymous)
94
- **Internal** — authenticated users can read
95
- **Private** — team members only
96
97
### Encryption
98
99
SSH keys and OAuth tokens encrypted at rest using Fernet (AES-128-CBC + HMAC-SHA256), keyed from Django's `SECRET_KEY`. Implemented as `EncryptedTextField` in `core/fields.py`.
100
101
## Infrastructure
102
103
### Docker (Omnibus)
104
105
Single multi-stage Dockerfile:
106
1. Stage 1: compile Fossil 2.24 from source (Debian bookworm)