FossilRepo

fossilrepo / docs / getting-started / installation.md

Source Blame History 113 lines

45192ef…	ragelink	1	# Setup Guide
2eca4eb…	ragelink	2
45192ef…	ragelink	3	## Quick Start (Docker)
2eca4eb…	ragelink	4
2eca4eb…	ragelink	5	```bash
2eca4eb…	ragelink	6	git clone https://github.com/ConflictHQ/fossilrepo.git
2eca4eb…	ragelink	7	cd fossilrepo
45192ef…	ragelink	8	docker compose up -d --build
45192ef…	ragelink	9	docker compose exec backend python manage.py migrate
45192ef…	ragelink	10	docker compose exec backend python manage.py seed
45192ef…	ragelink	11	docker compose exec backend python manage.py seed_roles
45192ef…	ragelink	12	```
45192ef…	ragelink	13
45192ef…	ragelink	14	Visit http://localhost:8000. Login: `admin` / `admin`.
45192ef…	ragelink	15
45192ef…	ragelink	16	## Default Users
45192ef…	ragelink	17
45192ef…	ragelink	18	\| Username \| Password \| Role \|
45192ef…	ragelink	19	\|----------\|----------\|------\|
45192ef…	ragelink	20	\| admin \| admin \| Superuser \|
45192ef…	ragelink	21	\| viewer \| viewer \| View-only \|
45192ef…	ragelink	22	\| role-admin \| role-admin \| Admin role \|
45192ef…	ragelink	23	\| role-manager \| role-manager \| Manager role \|
45192ef…	ragelink	24	\| role-developer \| role-developer \| Developer role \|
45192ef…	ragelink	25	\| role-viewer \| role-viewer \| Viewer role \|
45192ef…	ragelink	26
45192ef…	ragelink	27	## Configuration
45192ef…	ragelink	28
45192ef…	ragelink	29	### Environment Variables
45192ef…	ragelink	30
45192ef…	ragelink	31	Copy `.env.example` to `.env` and customize. Key variables:
45192ef…	ragelink	32
45192ef…	ragelink	33	\| Variable \| Default \| Description \|
45192ef…	ragelink	34	\|----------\|---------\|-------------\|
45192ef…	ragelink	35	\| DJANGO_SECRET_KEY \| change-me \| Required in production \|
45192ef…	ragelink	36	\| DJANGO_DEBUG \| false \| Enable debug mode \|
45192ef…	ragelink	37	\| DJANGO_ALLOWED_HOSTS \| localhost \| Comma-separated hostnames \|
45192ef…	ragelink	38	\| POSTGRES_DB \| fossilrepo \| Database name \|
45192ef…	ragelink	39	\| POSTGRES_USER \| dbadmin \| Database user \|
45192ef…	ragelink	40	\| POSTGRES_PASSWORD \| Password123 \| Database password \|
45192ef…	ragelink	41	\| REDIS_URL \| redis://localhost:6379/1 \| Redis connection \|
45192ef…	ragelink	42	\| EMAIL_HOST \| localhost \| SMTP server \|
45192ef…	ragelink	43	\| CORS_ALLOWED_ORIGINS \| http://localhost:8000 \| CORS origins \|
45192ef…	ragelink	44	\| SENTRY_DSN \| (empty) \| Sentry error tracking \|
45192ef…	ragelink	45
45192ef…	ragelink	46	### Runtime Settings (Constance)
45192ef…	ragelink	47
45192ef…	ragelink	48	Configurable via Django admin at `/admin/constance/config/`:
45192ef…	ragelink	49
45192ef…	ragelink	50	\| Setting \| Default \| Description \|
45192ef…	ragelink	51	\|---------\|---------\|-------------\|
45192ef…	ragelink	52	\| SITE_NAME \| Fossilrepo \| Display name \|
45192ef…	ragelink	53	\| FOSSIL_DATA_DIR \| /data/repos \| Where .fossil files live \|
45192ef…	ragelink	54	\| FOSSIL_BINARY_PATH \| fossil \| Path to fossil binary \|
45192ef…	ragelink	55	\| FOSSIL_STORE_IN_DB \| false \| Store snapshots via Django file storage \|
45192ef…	ragelink	56	\| FOSSIL_S3_TRACKING \| false \| Track S3 replication \|
45192ef…	ragelink	57	\| GIT_SYNC_MODE \| disabled \| Default sync mode \|
45192ef…	ragelink	58	\| GIT_SYNC_SCHEDULE \| /15 * * * \| Default cron for git sync \|
45192ef…	ragelink	59
45192ef…	ragelink	60	### OAuth (GitHub/GitLab)
45192ef…	ragelink	61
45192ef…	ragelink	62	For Git mirror sync via OAuth:
45192ef…	ragelink	63	1. Create an OAuth App on GitHub/GitLab
45192ef…	ragelink	64	2. Set Client ID and Secret in Constance (Django admin)
45192ef…	ragelink	65	3. Callback URLs are handled automatically
45192ef…	ragelink	66
45192ef…	ragelink	67	## Adding Repositories
45192ef…	ragelink	68
45192ef…	ragelink	69	### Create Empty
45192ef…	ragelink	70
45192ef…	ragelink	71	1. Go to Projects > + New
45192ef…	ragelink	72	2. Fill in name and description
45192ef…	ragelink	73	3. Select "Create empty repository"
45192ef…	ragelink	74	4. Done — empty .fossil file created
45192ef…	ragelink	75
45192ef…	ragelink	76	### Clone from Fossil URL
45192ef…	ragelink	77
45192ef…	ragelink	78	1. Go to Projects > + New
45192ef…	ragelink	79	2. Select "Clone from Fossil URL"
45192ef…	ragelink	80	3. Enter the URL (e.g., `https://fossil-scm.org/home`)
45192ef…	ragelink	81	4. FossilRepo clones the repo and links it
45192ef…	ragelink	82
45192ef…	ragelink	83	### Clone Fossil SCM (Example)
45192ef…	ragelink	84
45192ef…	ragelink	85	```bash
45192ef…	ragelink	86	# Clone the official Fossil SCM repo
45192ef…	ragelink	87	docker compose exec backend fossil clone https://fossil-scm.org/home /data/repos/fossil-scm.fossil
45192ef…	ragelink	88	```
45192ef…	ragelink	89
45192ef…	ragelink	90	Then create a Project in the UI and link it to the file.
45192ef…	ragelink	91
45192ef…	ragelink	92	## Production Deployment
45192ef…	ragelink	93
45192ef…	ragelink	94	See `.env.production.example` for production settings. Key steps:
45192ef…	ragelink	95
45192ef…	ragelink	96	1. Set a strong `DJANGO_SECRET_KEY`
45192ef…	ragelink	97	2. Set `DJANGO_DEBUG=false`
45192ef…	ragelink	98	3. Configure `DJANGO_ALLOWED_HOSTS` to your domain
45192ef…	ragelink	99	4. Use a proper database password
45192ef…	ragelink	100	5. Configure email (SES, SMTP)
45192ef…	ragelink	101	6. Set up HTTPS via Caddy or reverse proxy
45192ef…	ragelink	102	7. Configure S3 for Litestream backups (optional)
45192ef…	ragelink	103
45192ef…	ragelink	104	## Ports
45192ef…	ragelink	105
45192ef…	ragelink	106	\| Port \| Service \|
45192ef…	ragelink	107	\|------\|---------\|
45192ef…	ragelink	108	\| 8000 \| Django (HTTP) \|
45192ef…	ragelink	109	\| 2222 \| SSH (Fossil sync) \|
45192ef…	ragelink	110	\| 5432 \| PostgreSQL \|
45192ef…	ragelink	111	\| 6379 \| Redis \|
45192ef…	ragelink	112	\| 1025 \| Mailpit SMTP (dev) \|
45192ef…	ragelink	113	\| 8025 \| Mailpit UI (dev) \|

FossilRepo

Keyboard Shortcuts