vole
Clone
Read only, no credentials:
https://rodent.software/vole.git
Write over SSH with a registered key:
git clone ssh://git@rodent.software:2222/vole.git
A free and open-source forge that lives in your Git repo.
| 1 | # Vole documentation |
| 2 | |
| 3 | Vole is a forge that lives in your Git repo. It is for developers and small |
| 4 | teams who want their repository to keep working even when someone else's cloud |
| 5 | does not. |
| 6 | |
| 7 | New to Vole? Start with [Getting started](getting-started.md). It takes you from a |
| 8 | source checkout to a repository you can clone. |
| 9 | |
| 10 | After that, pick the page that matches what you want to do. |
| 11 | |
| 12 | ## Everyday use |
| 13 | |
| 14 | | Page | What it helps you do | |
| 15 | |---|---| |
| 16 | | [Getting started](getting-started.md) | Build Vole, create an account, and make your first repository | |
| 17 | | [Issues](issues.md) | Track bugs and tasks, comment on them, and edit them | |
| 18 | | [Change requests](change-requests.md) | Ask for a change request to be reviewed, approved, and merged | |
| 19 | | [Workflows](workflows.md) | Add workflows, define jobs, and publish artifacts | |
| 20 | | [Runners](runner.md) | Start a machine, execute jobs, and report results | |
| 21 | | [LFS](lfs.md) | Store large files and lock files that Git cannot merge | |
| 22 | | [Releases](releases.md) | Publish a release with notes, source archives, and binaries | |
| 23 | | [Sites](sites.md) | Serve a repository branch as a website | |
| 24 | | [Go modules](go-modules.md) | Import a public repository with `go get`, with no vanity service in front of the forge | |
| 25 | |
| 26 | ## Reference |
| 27 | |
| 28 | | Page | What it helps you do | |
| 29 | |---|---| |
| 30 | | [Workflow reference](reference/workflow-reference.md) | Look up every workflow field, limit, and default | |
| 31 | | [Image reference](reference/image-reference.md) | Look up every `.vole/images` field, limit, and default | |
| 32 | |
| 33 | ## Running an instance |
| 34 | |
| 35 | | Page | What it helps you do | |
| 36 | |---|---| |
| 37 | | [Deploying](deploy/README.md) | Put an instance on a server with a first-boot file | |
| 38 | | [Configuration](configuration.md) | Change addresses, limits, and site settings | |
| 39 | | [Accounts and access](accounts-and-access.md) | Add accounts, manage SSH keys, and set permissions | |
| 40 | | [Operations](operations.md) | Back up, recover, and clean up an instance | |
| 41 | | [Load testing](load-testing.md) | Measure throughput and latency on a real instance | |
| 42 | | [Packages](packaging.md) | Build, install, and upgrade a `.deb` or `.rpm` | |
| 43 | | [CLI reference](cli.md) | Look up a command or option | |
| 44 | |
| 45 | ## Design |
| 46 | |
| 47 | [Architecture](architecture.md) explains how trust, storage, and the code are |
| 48 | organized. |
| 49 | |
| 50 | ## Terminology |
| 51 | |
| 52 | Use one word for each concept, in the interface and the guides: |
| 53 | |
| 54 | - **account**: the identity that owns keys, passkeys, sessions, and roles. The CLI |
| 55 | spells its commands `vole admin account ...`; `vole admin user ...` remains as |
| 56 | an alias. The database file is `data/users.db`; in prose it is still an account. |
| 57 | - **repository**: the Git repository and what belongs to it. The CLI uses `repo`, |
| 58 | URLs use `/<name>`, and the forge's own pages live under `/-/`; do not call it a |
| 59 | project. |
| 60 | - **change request**: a proposed branch reviewed before landing. The CLI uses |
| 61 | `change` and the route is `/changes`. |
| 62 | - **enrollment link**: the one-time link that lets someone register a passkey and |
| 63 | sign in. The CLI command is `vole admin account invite`, and some code calls it |
| 64 | an invite. |
| 65 | - **instance admin**: the instance-wide `admin` role. Say "instance admin", not |
| 66 | "administrator", when that is what you mean. |
| 67 | - **sign in** / **sign out**: the browser action. `login` and `logout` remain in |
| 68 | routes, setting names, and code. |
| 69 | |
| 70 | The `data/users.db` filename and the `user` command aliases keep their |
| 71 | historical spellings; everything the interface and documentation say uses the |
| 72 | words above. |
| 73 | |
| 74 | ## A few conventions |
| 75 | |
| 76 | - Examples assume `vole` is on your `PATH`, or that you are running `./vole` from |
| 77 | the repository root. |
| 78 | - Use `--remote <name>` when a clone has more than one remote. The default is |
| 79 | `origin`. |
| 80 | - Commands accept options in the same styles Git does: `--long value`, |
| 81 | `--long=value`, `-o value`, `-ovalue`, repeated options, and `--` to stop |
| 82 | option parsing. |
| 83 | - Commands that write data need a Git remote. Read-only commands such as |
| 84 | `vole issue list` work from a clone without network access. |
| 85 |