# 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 (`//.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 --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.