123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899
# Forge
Forge is a self-hosted Git server with a web interface. It is built with ASP.NET Core (Blazor Server) and uses real bare Git repositories on disk, so any Git client can clone and push to it over HTTP(S).
## Features
- **Repositories:** create repos, browse files and folders, view blobs with syntax highlighting, and render Markdown previews.
- **History:** commit list and commit details, branch and tag pages, compare any two refs, and a file-level diff view.
- **Pull requests:** open, review and merge pull requests, with merge-conflict detection (`git merge-tree`) and branch protection rules.
- **Search:** find repositories, file names and file contents.
- **Activity:** weekly commit counts and contributors per repository.
- **Git over HTTP:** clone and push with the smart HTTP protocol. Authentication uses personal access tokens (read-only or read/write).
- **Webhooks:** signed deliveries for pushes and pull request events, with delivery status and retries.
- **Atom feeds:** commit feeds for each repository.
- **Accounts:** sign-up through a first-run setup page, login with rate limiting, and per-user repository access.
- **Languages:** English and Slovak. The language is chosen in the footer and remembered in a cookie, with the browser's `Accept-Language` as the fallback.
## Requirements
- [.NET SDK](https://dotnet.microsoft.com/download) with the version targeted in `forge/forge.csproj`
- Git 2.40 or newer (Forge uses `git merge-tree --merge-base`). Forge checks the version at startup and refuses to run with an older one.
## Getting started
```bash
dotnet run --project forge
```
The default development profile listens on `http://localhost:5207`. On first run, open `/setup` to create the administrator account. Then create a repository at `/new`.
To clone a repository from Forge, use the URL shown on the repository page (`<BaseUrl>/<owner>/<name>.git`). Git asks for credentials: use your username, and a personal access token created at `/settings/tokens` as the password.
## Configuration
Settings live in `forge/appsettings.json` under the `Forge` section. Any of them can be overridden with environment variables (for example `Forge__BaseUrl`) or with user secrets during development.
| Setting | Default | Meaning |
| --- | --- | --- |
| `Forge:DataPath` | `data` | Folder for `forge.db` and the `repos/` directory. Relative paths resolve against the working directory. |
| `Forge:BaseUrl` | `http://localhost:5207` | Public URL of the site. Used for clone URLs, feeds and webhook payloads. Must be an absolute http or https URL. |
| `Forge:MaxPushSizeMb` | `500` | Largest push Forge accepts, in megabytes. |
| `Forge:GitPath` | `git` | Git executable, a name on `PATH` or an absolute path. |
Set `BaseUrl` to the address users actually visit. Using `https://` also makes the session and CSRF cookies `Secure`.
## Deploying with Docker
The `Dockerfile` builds an image with the app and git, running as a non-root user on port 8080, with all data in the `/data` volume. With Docker Compose:
1. Set `Forge__BaseUrl` in `compose.yaml` to the public address of the server.
2. Run `docker compose up -d --build`.
3. Open `/setup` to create the administrator account.
`compose.yaml` publishes the port on `127.0.0.1` only, for a reverse proxy that terminates HTTPS. Forwarded headers (`X-Forwarded-For`, `X-Forwarded-Proto`) are honored, so rate limiting sees real client addresses. Allow request bodies as large as `Forge:MaxPushSizeMb` in the proxy (for nginx, `client_max_body_size`), and pass WebSocket upgrades through, which Blazor Server uses.
To update, pull the new code and run `docker compose up -d --build` again. Migrations run at startup.
## Data and storage
- `forge.db` is a SQLite database managed with Entity Framework Core. Migrations run automatically at startup.
- `repos/` holds the bare Git repositories.
- `keys/` holds the keys that protect login cookies. Losing them signs everyone out.
- Both live under `Forge:DataPath`. Back up that folder to back up the server.
## Project layout
```
forge/ ASP.NET Core application
Components/ Shared Blazor components and layout
Features/ Feature folders: Auth, Browse, History, Pulls, Repos, SmartHttp, Webhooks
Git/ Thin wrapper around the git executable and its output parsers
Data/ EF Core model, DbContext and migrations
Localization/ Translation files (sk.json; English is the source language)
wwwroot/ Static assets (CSS, JavaScript, syntax highlighting)
forge.Tests/ xUnit tests, including end-to-end tests that run the app and real Git
```
## Development
```bash
dotnet build forge.slnx
dotnet test forge.Tests
```
Adding a language means adding a JSON file to `forge/Localization/`, named after its culture code (for example `de.json`). Keys are the English strings exactly as they appear in the code.
Database schema changes are made with the EF Core tools in `dotnet-tools.json`:
```bash
dotnet ef migrations add <Name> --project forge
```
## Security notes
- Passwords are hashed with ASP.NET Core Identity's `PasswordHasher`.
- Access tokens are used as the Git password. Read-only tokens cannot push.
- Responses set a strict Content-Security-Policy, `X-Frame-Options: DENY` and `nosniff`.
- Form posts are rate limited per client address. Rendered Markdown is sanitized.
- Webhook receivers are not followed on redirect, so signed payloads are never re-sent to another address.