FossilRepo

fossilrepo / README.md
Source Rendered
Blame History Raw 194 lines
1
# Fossilrepo
2
3
**Self-hosted Fossil forge with a modern web interface.**
4
5
![FossilRepo Tour](docs/fossilrepo-tour.gif)
6
7
Fossilrepo wraps [Fossil SCM](https://fossil-scm.org) with a Django + HTMX management layer, replacing Fossil's built-in web UI with a GitHub/GitLab-caliber experience while preserving everything that makes Fossil unique: single-file repos, built-in wiki, tickets, forum, and technotes.
8
9
**Live instance:** [fossilrepo.io](https://fossilrepo.io) | **Docs:** [fossilrepo.dev](https://fossilrepo.dev) | **Powered by [BoilerWorks](https://boilerworks.ai)**
10
11
## Why Fossilrepo?
12
13
Fossil is the most underrated version control system. Every repository is a single SQLite file containing your code, wiki, tickets, forum, and technotes. No external services, no complex setup. But its web UI hasn't changed since 1998.
14
15
Fossilrepo fixes that. You get:
16
17
- A modern dark/light UI built with Django, HTMX, Alpine.js, and Tailwind CSS
18
- GitHub-style code browser with line numbers, blame, history, and syntax highlighting
19
- Timeline with DAG graph showing fork/merge connectors and color-coded branches
20
- Full ticket CRUD with filters, comments, and CSV export
21
- Wiki with Markdown + Fossil markup + Pikchr diagram rendering
22
- Forum with threaded discussions
23
- Releases with file attachments and markdown changelogs
24
- Git mirror sync to GitHub/GitLab via OAuth
25
- Clone/push/pull over HTTP and SSH through Django's auth layer
26
- Webhook dispatch with HMAC signing and delivery logs
27
- Omnibus Docker image with Fossil compiled from source
28
29
All while Fossil remains the source of truth. Fossilrepo reads `.fossil` files directly via SQLite for speed, and uses the `fossil` CLI for writes to preserve artifact integrity.
30
31
## Stack
32
33
| Layer | Technology |
34
|-------|-----------|
35
| Backend | Django 5 (Python 3.12+) |
36
| Frontend | HTMX 2.0 + Alpine.js 3 + Tailwind CSS (CDN) |
37
| Database | PostgreSQL 16 (app data) + SQLite (Fossil repos) |
38
| Cache/Broker | Redis 7 |
39
| Jobs | Celery + Redis |
40
| Auth | Session-based (httpOnly cookies) |
41
| SCM | Fossil 2.24 (compiled from source in Docker) |
42
| Linter | Ruff |
43
44
## Quick Start
45
46
```bash
47
git clone https://github.com/ConflictHQ/fossilrepo.git
48
cd fossilrepo
49
docker compose up -d --build
50
51
# Run migrations and seed sample data
52
docker compose exec backend python manage.py migrate
53
docker compose exec backend python manage.py seed
54
55
# Open the app
56
open http://localhost:8000
57
```
58
59
**Default users:** `admin` / `admin` (superuser) and `viewer` / `viewer` (read-only).
60
61
## Features
62
63
### Code Browser
64
- Directory navigation with breadcrumbs
65
- Syntax-highlighted source view with line numbers and permalinks
66
- Blame with age-based coloring (newest = brand red, oldest = gray)
67
- File history, raw download, rendered preview for Markdown/HTML
68
69
### Timeline
70
- DAG graph with fork/merge connectors, color-coded branches
71
- Merge commit diamonds, leaf indicators
72
- Keyboard navigation (j/k/Enter), HTMX infinite scroll
73
- RSS feed
74
75
### Diffs
76
- Unified and side-by-side view (toggle with localStorage preference)
77
- Syntax highlighting via highlight.js
78
- Line-level permalinks
79
- Compare any two checkins
80
81
### Tickets
82
- Filter by status, type, priority, severity
83
- Full CRUD: create, edit, close/reopen, comment
84
- CSV export
85
- Pagination with configurable page size
86
87
### Wiki
88
- Markdown + Fossil wiki markup + raw HTML
89
- Pikchr diagram rendering
90
- Right-sidebar table of contents
91
- Create and edit pages
92
93
### Forum
94
- Threaded discussions (Fossil-native + Django-backed posts)
95
- Create threads, post replies
96
- Markdown body with preview
97
98
### Releases
99
- Versioned releases with tag names and markdown changelogs
100
- File attachments with download counts
101
- Draft and prerelease support
102
103
### Sync
104
- Pull from upstream Fossil remotes
105
- Git mirror to GitHub/GitLab (OAuth or SSH key auth)
106
- Clone/push/pull over HTTP via `fossil http` CGI proxy
107
- SSH push via restricted sshd (port 2222)
108
- Configurable sync modes: on-change, scheduled, both
109
110
### Webhooks
111
- Outbound webhooks on checkin, ticket, wiki, and release events
112
- HMAC-SHA256 signed payloads
113
- Exponential backoff retry (3 attempts)
114
- Delivery log with response status and timing
115
116
### Organization
117
- Single-org model with teams and members
118
- User CRUD: create, edit, deactivate, change password
119
- Team management with member assignment
120
- Project-level team roles: read, write, admin
121
- Project visibility: public, internal, private
122
123
### Infrastructure
124
- Omnibus Docker image (Fossil compiled from source)
125
- Caddy for SSL termination and subdomain routing
126
- Litestream for continuous SQLite-to-S3 replication
127
- Celery Beat for scheduled metadata sync and upstream checks
128
- Encrypted credential storage (Fernet/AES-128-CBC at rest)
129
130
## Architecture
131
132
```
133
Browser
134
|
135
v
136
Django 5 + HTMX + Alpine.js + Tailwind CSS
137
|
138
|-- FossilReader (direct SQLite reads from .fossil files)
139
|-- FossilCLI (subprocess wrapper for write operations)
140
|-- fossil http (CGI proxy for clone/push/pull)
141
|
142
|-- PostgreSQL 16 (orgs, users, teams, projects, settings)
143
|-- Redis 7 (Celery broker, cache)
144
|-- Celery (background sync, webhooks, notifications)
145
|
146
v
147
.fossil files (SQLite — code + wiki + tickets + forum + technotes)
148
|
149
v
150
Litestream --> S3 (continuous backup)
151
```
152
153
No separate frontend service. Django serves everything: templates, static files, and HTMX partials.
154
155
## Configuration
156
157
All runtime settings are configurable via Django admin (Constance):
158
159
| Setting | Default | Description |
160
|---------|---------|-------------|
161
| `SITE_NAME` | Fossilrepo | Display name |
162
| `FOSSIL_DATA_DIR` | /data/repos | Where .fossil files live |
163
| `FOSSIL_BINARY_PATH` | fossil | Path to the fossil binary |
164
| `FOSSIL_STORE_IN_DB` | false | Store .fossil snapshots via Django file storage |
165
| `FOSSIL_S3_TRACKING` | false | Track S3/Litestream replication |
166
| `GIT_SYNC_MODE` | disabled | Default sync mode for new mirrors |
167
| `GIT_SYNC_SCHEDULE` | */15 * * * * | Default cron for scheduled sync |
168
169
See [`.env.example`](.env.example) for all environment variables and [`.env.production.example`](.env.production.example) for production configuration.
170
171
## Development
172
173
```bash
174
# Local development (without Docker)
175
uv sync --all-extras
176
DJANGO_DEBUG=true POSTGRES_HOST=localhost uv run python manage.py runserver
177
178
# Run tests
179
DJANGO_DEBUG=true uv run pytest
180
181
# Lint
182
ruff check . && ruff format --check .
183
```
184
185
See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the full development guide and [`bootstrap.md`](bootstrap.md) for codebase conventions.
186
187
## License
188
189
MIT License. See [LICENSE](LICENSE) for details.
190
191
---
192
193
Built by [CONFLICT](https://weareconflict.com). Fossilrepo is open source under the MIT license.
194

Keyboard Shortcuts

Open search /
Next entry (timeline) j
Previous entry (timeline) k
Open focused entry Enter
Show this help ?
Toggle theme Top nav button