vole
Clone
Read only, no credentials:
https://rodent.software/git/vole.git
Write over SSH with a registered key:
git clone ssh://git@0.0.0.0:2222/vole.git
A free and open-source forge that lives in your Git repo.
Docs: rewrite the README and organize the guides
520470e19cd906bd6fff987e2d132d793ce56486 · Keenan Nemetz · 16d ago · parent c5902451
Docs: rewrite the README and organize the guides Replace the long README with a landing page, split feature details into focused guides, and remove the roadmap and spike notes. Update comments that referenced them.
docs/configuration.md +86
| @@ -0,0 +1,86 @@ | |||
| 1 | # Configuration | ||
| 2 | |||
| 3 | Vole is designed to work out of the box. The defaults are enough for a local | ||
| 4 | instance. Change them when you want Vole to listen on another address, limit what | ||
| 5 | people can push, or serve websites. | ||
| 6 | |||
| 7 | There is no control panel. One TOML file is the whole configuration. | ||
| 8 | |||
| 9 | ## A minimal config | ||
| 10 | |||
| 11 | ```toml | ||
| 12 | data_dir = "./data" | ||
| 13 | http_addr = "127.0.0.1:8080" | ||
| 14 | ssh_addr = "127.0.0.1:2222" | ||
| 15 | # public_url = "https://forge.example.com" | ||
| 16 | ``` | ||
| 17 | |||
| 18 | ## Settings | ||
| 19 | |||
| 20 | | Setting | Default | What it does | | ||
| 21 | |---|---:|---| | ||
| 22 | | `data_dir` | `"./data"` | Where Vole keeps repositories, databases, stored files, and the audit log | | ||
| 23 | | `http_addr` | `"127.0.0.1:8080"` | Address for the read-only web interface and anonymous Git clone | | ||
| 24 | | `ssh_addr` | `"127.0.0.1:2222"` | Address for SSH, the only way to write | | ||
| 25 | | `public_url` | empty | The address people use in a browser, so the CLI can print useful links | | ||
| 26 | | `max_blob_bytes` | `104857600` (100 MiB) | Largest single file accepted in a push | | ||
| 27 | | `receive_max_bytes` | `1073741824` (1 GiB) | Largest whole push Vole will accept | | ||
| 28 | | `lfs_object_max_bytes` | `2147483648` (2 GiB) | Largest single LFS object | | ||
| 29 | | `lfs_warn_bytes` | `5242880` (5 MiB) | Warn when a large binary is committed outside LFS; `0` turns the warning off | | ||
| 30 | | `lease_seconds` | `60` | How long a runner may hold a job without checking in before it is given to someone else | | ||
| 31 | | `max_jobs_per_repo` | `0` | How many jobs one repository may run at once; `0` means no limit | | ||
| 32 | | `pages_domain` | empty | Domain suffix for websites, as in `<repo>.<pages_domain>`; empty disables sites | | ||
| 33 | | `pages_ref` | `"pages"` | Branch served as a website | | ||
| 34 | | `pages_procs` | `4` | Number of Git reader processes per active site | | ||
| 35 | | `pages_cache_bytes` | `33554432` (32 MiB) | Memory used to cache site files | | ||
| 36 | |||
| 37 | The two push limits work at different levels. `max_blob_bytes` checks each file in | ||
| 38 | a push. `receive_max_bytes` caps the size of the whole push and is enforced by Git | ||
| 39 | while it receives the data, before any branch is updated. | ||
| 40 | |||
| 41 | ## Public URL | ||
| 42 | |||
| 43 | Set `public_url` when people reach Vole through a different address than | ||
| 44 | `http_addr`, for example through a proxy: | ||
| 45 | |||
| 46 | ```toml | ||
| 47 | public_url = "https://forge.example.com" | ||
| 48 | ``` | ||
| 49 | |||
| 50 | The CLI uses this to print a link to an issue, comment, or release it just | ||
| 51 | created. It does not change how Vole routes requests. | ||
| 52 | |||
| 53 | ## Running behind a proxy | ||
| 54 | |||
| 55 | Vole serves plain HTTP. If the instance is public, terminate TLS in a proxy in | ||
| 56 | front of `http_addr`. Keep the `Host` header intact: Vole uses it to decide which | ||
| 57 | site a request belongs to. | ||
| 58 | |||
| 59 | ```nginx | ||
| 60 | server { | ||
| 61 | listen 443 ssl; | ||
| 62 | server_name *.forge.example.com; | ||
| 63 | location / { | ||
| 64 | proxy_set_header Host $host; | ||
| 65 | proxy_set_header X-Forwarded-Proto $scheme; | ||
| 66 | proxy_pass http://127.0.0.1:8080; | ||
| 67 | } | ||
| 68 | } | ||
| 69 | ``` | ||
| 70 | |||
| 71 | SSH is separate. Expose `ssh_addr` directly, or through a TCP proxy that keeps the | ||
| 72 | connection intact. | ||
| 73 | |||
| 74 | ## What Vole stores | ||
| 75 | |||
| 76 | | Path | What it is | | ||
| 77 | |---|---| | ||
| 78 | | `data/users.db` | Accounts, names, SSH keys, access rules, and locks. This is the main user database. | | ||
| 79 | | `data/repos/` | Your Git repositories. | | ||
| 80 | | `data/index.db` | A rebuildable search index. | | ||
| 81 | | `data/runs.db` | The CI queue and finished-run index. Partly rebuildable. | | ||
| 82 | | `data/lfs/` | Stored large files, CI logs, and build artifacts. | | ||
| 83 | | `data/audit.log` | A record of privileged actions. | | ||
| 84 | | `data/ssh_host_ed25519_key` | The SSH host key. It is the only secret Vole keeps. | | ||
| 85 | |||
| 86 | See [Operations](operations.md) for backup and recovery. | ||