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

FossilRepo

Keyboard Shortcuts