Setup Guide

Quick Start (Docker)

git clone https://github.com/ConflictHQ/fossilrepo.git
cd fossilrepo
docker compose up -d --build
docker compose exec backend python manage.py migrate
docker compose exec backend python manage.py seed
docker compose exec backend python manage.py seed_roles

Visit http://localhost:8000. Login: admin / admin.

Default Users

| Username | Password | Role |

|---|

| admin | admin | Superuser |

| viewer | viewer | View-only |

| role-admin | role-admin | Admin role |

| role-manager | role-manager | Manager role |

| role-developer | role-developer | Developer role |

| role-viewer | role-viewer | Viewer role |

Configuration

Environment Variables

Copy .env.example to .env and customize. Key variables:

| Variable | Default | Description |

|---|

| DJANGO_SECRET_KEY | change-me | Required in production |

| DJANGO_DEBUG | false | Enable debug mode |

| DJANGO_ALLOWED_HOSTS | localhost | Comma-separated hostnames |

| POSTGRES_DB | fossilrepo | Database name |

| POSTGRES_USER | dbadmin | Database user |

| POSTGRES_PASSWORD | Password123 | Database password |

| REDIS_URL | redis://localhost:6379/1 | Redis connection |

| EMAIL_HOST | localhost | SMTP server |

| CORS_ALLOWED_ORIGINS | http://localhost:8000 | CORS origins |

| SENTRY_DSN | (empty) | Sentry error tracking |

Runtime Settings (Constance)

Configurable via Django admin at /admin/constance/config/:

| Setting | Default | Description |

|---|

| SITE_NAME | Fossilrepo | Display name |

| FOSSIL_DATA_DIR | /data/repos | Where .fossil files live |

| FOSSIL_BINARY_PATH | fossil | Path to fossil binary |

| FOSSIL_STORE_IN_DB | false | Store snapshots via Django file storage |

| FOSSIL_S3_TRACKING | false | Track S3 replication |

| GIT_SYNC_MODE | disabled | Default sync mode |

| GIT_SYNC_SCHEDULE | */15 * * * * | Default cron for git sync |

OAuth (GitHub/GitLab)

For Git mirror sync via OAuth: 1. Create an OAuth App on GitHub/GitLab 2. Set Client ID and Secret in Constance (Django admin) 3. Callback URLs are handled automatically

Adding Repositories

Create Empty

• Go to Projects > + New

• Fill in name and description

• Select "Create empty repository"

• Done — empty .fossil file created

Clone from Fossil URL

• Go to Projects > + New

• Select "Clone from Fossil URL"

• Enter the URL (e.g., https://fossil-scm.org/home)

• FossilRepo clones the repo and links it

Clone Fossil SCM (Example)

# Clone the official Fossil SCM repo
docker compose exec backend fossil clone https://fossil-scm.org/home /data/repos/fossil-scm.fossil

Then create a Project in the UI and link it to the file.

Production Deployment

See .env.production.example for production settings. Key steps:

• Set a strong DJANGO_SECRET_KEY

• Set DJANGO_DEBUG=false

• Configure DJANGO_ALLOWED_HOSTS to your domain

• Use a proper database password

• Configure email (SES, SMTP)

• Set up HTTPS via Caddy or reverse proxy

• Configure S3 for Litestream backups (optional)

Ports

| Port | Service |

|---|

| 8000 | Django (HTTP) |

| 2222 | SSH (Fossil sync) |

| 5432 | PostgreSQL |

| 6379 | Redis |

| 1025 | Mailpit SMTP (dev) |

| 8025 | Mailpit UI (dev) |

Z