Public
Open-source lightweight git hosting.
Update README.md
f3c5a2b
Browse files
Signed-off-by: rinusho <rinusho@noreply.codeberg.org>
R
rinusho
·
2026-10-16 14:36 UTC
1 file changed
+188
-2
README.md
+188
-2
| ... | ... | @@ -1,3 +1,189 @@ |
| 1 | -# ada | |
| 1 | +# Polar | |
| 2 | 2 | |
| 3 | -Open-source lightweight git hub | |
| 3 | +**Lightweight self-hosted Git hosting in a single Go binary.** | |
| 4 | + | |
| 5 | +Polar is a small, fast alternative to heavyweight Git servers: push over HTTP, browse code, file issues, open pull requests, and publish releases — all served from one static binary with an embedded SQLite database and no external runtime dependencies. | |
| 6 | + | |
| 7 | +## Highlights | |
| 8 | + | |
| 9 | +- **One binary, zero dependencies** — `CGO_ENABLED=0` build, pure-Go SQLite (`modernc.org/sqlite`) in WAL mode, bare repositories stored on disk. | |
| 10 | +- **Git Smart HTTP** — anonymous read access for public repositories, token-authenticated push, per-user personal access tokens. | |
| 11 | +- **Code browsing** — file tree, blob viewer with server-side syntax highlighting (Chroma), commit history, diffs, branches, tags, and zip archives. | |
| 12 | +- **Collaboration** — issues with comments and open/close state, pull requests with review comments and merge, releases with changelogs. | |
| 13 | +- **Polished UI** — `html/template` + htmx, no SPA build step; Markdown rendered with Goldmark and sanitized with bluemonday; Hugeicons outline sprite; self-hosted Inter and JetBrains Mono fonts (Cyrillic subsets included). | |
| 14 | +- **Command palette** — press `Ctrl+K` / `Cmd+K` for quick navigation and actions. | |
| 15 | +- **Three themes** — Light (`#fff` background, `#111` foreground), Dark (`#111` background, `#fff` foreground), and System (follows the OS `prefers-color-scheme`). The choice is persisted in a `polar_theme` cookie so the server renders the correct `data-theme` on first paint — no flash of the wrong theme. | |
| 16 | +- **Bilingual interface** — Russian and English, with a configurable default language. | |
| 17 | +- **Practical security** — Argon2id password hashing, CSRF protection, rate-limited login and registration, session cookies, and revocable access tokens. | |
| 18 | + | |
| 19 | +## Quick Start | |
| 20 | + | |
| 21 | +### Build from source | |
| 22 | + | |
| 23 | +Requirements: Go (version per `go.mod`) and `git` available on the host. | |
| 24 | + | |
| 25 | +```bash | |
| 26 | +CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o polar ./cmd/polar | |
| 27 | +./polar | |
| 28 | +``` | |
| 29 | + | |
| 30 | +Polar starts on `0.0.0.0:3000` and keeps its data in `./data`. Open http://localhost:3000 and register — **the first registered account becomes the administrator**. After that you can disable public registration or manage users from the admin panel. | |
| 31 | + | |
| 32 | +### Docker | |
| 33 | + | |
| 34 | +```bash | |
| 35 | +docker compose up -d | |
| 36 | +``` | |
| 37 | + | |
| 38 | +Or without Compose: | |
| 39 | + | |
| 40 | +```bash | |
| 41 | +docker build -t polar . | |
| 42 | +docker run -d --name polar -p 3000:3000 -v "$PWD/data:/app/data" polar | |
| 43 | +``` | |
| 44 | + | |
| 45 | +### systemd | |
| 46 | + | |
| 47 | +```ini | |
| 48 | +# /etc/systemd/system/polar.service | |
| 49 | +[Unit] | |
| 50 | +Description=Polar Self-Hosted Git Server | |
| 51 | +After=network.target | |
| 52 | + | |
| 53 | +[Service] | |
| 54 | +Type=simple | |
| 55 | +User=polar | |
| 56 | +Group=polar | |
| 57 | +WorkingDirectory=/var/lib/polar | |
| 58 | +ExecStart=/usr/local/bin/polar -config /etc/polar/polar.toml | |
| 59 | +Environment=POLAR_STORAGE_DATA_DIR=/var/lib/polar/data | |
| 60 | +Restart=on-failure | |
| 61 | + | |
| 62 | +[Install] | |
| 63 | +WantedBy=multi-user.target | |
| 64 | +``` | |
| 65 | + | |
| 66 | +## Configuration | |
| 67 | + | |
| 68 | +Polar runs with sensible defaults and no config file. To customize, copy `polar.example.toml` to `polar.toml` (auto-detected in the working directory) or pass `-config /path/to/polar.toml`. Every setting can also be provided through environment variables, which take precedence over the file. | |
| 69 | + | |
| 70 | +```toml | |
| 71 | +[server] | |
| 72 | +host = "0.0.0.0" | |
| 73 | +port = 3000 | |
| 74 | +base_url = "http://localhost:3000" | |
| 75 | + | |
| 76 | +[storage] | |
| 77 | +data_dir = "./data" | |
| 78 | + | |
| 79 | +[auth] | |
| 80 | +registration_enabled = true | |
| 81 | + | |
| 82 | +[landing] | |
| 83 | +enabled = true | |
| 84 | +default_lang = "en" # "en" or "ru" | |
| 85 | +``` | |
| 86 | + | |
| 87 | +| Environment variable | Description | Default | | |
| 88 | +|---|---|---| | |
| 89 | +| `POLAR_SERVER_HOST` | HTTP listen host | `0.0.0.0` | | |
| 90 | +| `POLAR_SERVER_PORT` | HTTP listen port | `3000` | | |
| 91 | +| `POLAR_SERVER_BASE_URL` | Public URL used for clone links | `http://localhost:3000` | | |
| 92 | +| `POLAR_STORAGE_DATA_DIR` | Directory for the database and bare repositories | `./data` | | |
| 93 | +| `POLAR_AUTH_REGISTRATION_ENABLED` | Allow public registration | `true` | | |
| 94 | +| `POLAR_LANDING_ENABLED` | Serve the landing page at `/` | `true` | | |
| 95 | +| `POLAR_LANDING_DEFAULT_LANG` | Default UI language (`ru` or `en`) | `ru` | | |
| 96 | +| `POLAR_CONFIG` | Path to the configuration file | `polar.toml` if present | | |
| 97 | + | |
| 98 | +Short aliases are also accepted: `POLAR_HOST`, `POLAR_PORT`, `POLAR_BASE_URL`, `POLAR_DATA_DIR`. | |
| 99 | + | |
| 100 | +## Git over HTTP | |
| 101 | + | |
| 102 | +Clone a public repository: | |
| 103 | + | |
| 104 | +```bash | |
| 105 | +git clone http://localhost:3000/rin/demo.git | |
| 106 | +``` | |
| 107 | + | |
| 108 | +Push using a personal access token (create one in **Settings → Access tokens**; it is shown once and looks like `polar_...`): | |
| 109 | + | |
| 110 | +```bash | |
| 111 | +git clone http://localhost:3000/rin/demo.git | |
| 112 | +cd demo | |
| 113 | +git remote set-url origin http://rin:polar_XXXXXXXXXX@localhost:3000/rin/demo.git | |
| 114 | +git push | |
| 115 | +``` | |
| 116 | + | |
| 117 | +When git asks for credentials, use your username as the login and the token as the password. Tokens can be revoked at any time from the settings page. | |
| 118 | + | |
| 119 | +## Themes | |
| 120 | + | |
| 121 | +Polar ships exactly three themes, selectable from the theme switcher (or the command palette): | |
| 122 | + | |
| 123 | +| Theme | Background | Foreground | | |
| 124 | +|---|---|---| | |
| 125 | +| Light | `#fff` | `#111` | | |
| 126 | +| Dark | `#111` | `#fff` | | |
| 127 | +| System | follows the OS `prefers-color-scheme` | — | | |
| 128 | + | |
| 129 | +The active theme is saved to `localStorage` and a `polar_theme` cookie, so the server renders `<html data-theme="...">` immediately and there is no flash of the wrong theme on load. | |
| 130 | + | |
| 131 | +## Project Layout | |
| 132 | + | |
| 133 | +``` | |
| 134 | +polar/ | |
| 135 | +├── cmd/polar/main.go # Entry point, dependency wiring, graceful shutdown | |
| 136 | +├── internal/ | |
| 137 | +│ ├── config/ # polar.toml + POLAR_* environment overrides | |
| 138 | +│ ├── db/ # SQLite connection and migrations | |
| 139 | +│ ├── auth/ # Sessions, CSRF, Argon2id, access tokens | |
| 140 | +│ ├── user/ # User accounts and profiles | |
| 141 | +│ ├── repo/ # Repositories, issues, pull requests, releases | |
| 142 | +│ ├── git/ # Git plumbing (bare repos, commits, diffs) | |
| 143 | +│ ├── i18n/ # Russian and English message catalogs | |
| 144 | +│ └── web/ | |
| 145 | +│ ├── handlers/ # HTTP and Git Smart HTTP handlers | |
| 146 | +│ ├── middleware/ # Auth, CSRF, rate limiting, i18n | |
| 147 | +│ ├── views/ # html/template views | |
| 148 | +│ └── static/ # go:embed assets (CSS, JS, fonts, icons) | |
| 149 | +├── assets/input.css # Tailwind source for the generated stylesheet | |
| 150 | +├── polar.example.toml | |
| 151 | +├── Makefile | |
| 152 | +├── Dockerfile | |
| 153 | +└── docker-compose.yml | |
| 154 | +``` | |
| 155 | + | |
| 156 | +## Development | |
| 157 | + | |
| 158 | +```bash | |
| 159 | +make dev # run locally | |
| 160 | +make test # go test ./... | |
| 161 | +make lint # go vet ./... | |
| 162 | +make build # static binary with -trimpath -ldflags="-s -w" | |
| 163 | +make build-all # cross-compile Linux/macOS/Windows binaries into dist/ | |
| 164 | +make css # rebuild internal/web/static/css/app.css (requires the Tailwind CLI) | |
| 165 | +``` | |
| 166 | + | |
| 167 | +All runtime assets are embedded with `go:embed` — the binary needs no external CDN or asset directory. See `THIRD_PARTY.md` for licenses of bundled assets (Hugeicons icons, Inter and JetBrains Mono fonts, htmx) and Go dependencies. | |
| 168 | + | |
| 169 | +## Data and Backups | |
| 170 | + | |
| 171 | +``` | |
| 172 | +data/ | |
| 173 | +├── polar.db # SQLite database (WAL mode) | |
| 174 | +└── repos/ # Bare Git repositories, e.g. repos/rin/demo.git | |
| 175 | +``` | |
| 176 | + | |
| 177 | +Safe backup while Polar is running: | |
| 178 | + | |
| 179 | +```bash | |
| 180 | +sqlite3 data/polar.db "VACUUM INTO 'data/polar-backup.db';" | |
| 181 | +tar -czf polar-backup-$(date +%F).tar.gz data/polar-backup.db data/repos/ | |
| 182 | +rm data/polar-backup.db | |
| 183 | +``` | |
| 184 | + | |
| 185 | +To restore, stop Polar, replace `data/polar.db` and `data/repos/` with the backup contents, and start it again. | |
| 186 | + | |
| 187 | +## Health Check | |
| 188 | + | |
| 189 | +`GET /healthz` returns JSON with the database status — handy for Docker health checks and load balancers. |