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.

Blame · docs/deploy/aws.md

Line attribution on main · 139 line(s)

View file History

b8e7a567 Keenan Nemetz 3d ago	1	# Vole on AWS
b8e7a567 Keenan Nemetz 3d ago	2
942c93cd Keenan Nemetz 3d ago	3	One EC2 instance, configured on its first boot by a file you paste into the launch
	4	form. AWS differs from the other two guides in one way that matters: a new
	5	instance gets a security group that allows nothing inbound, so the security group
	6	is not optional here.
b8e7a567 Keenan Nemetz 3d ago	7
	8	## What you need
	9
942c93cd Keenan Nemetz 3d ago	10	- An AWS account, and a region you are happy to keep a team's forge in.
	11	- A DNS name, such as `forge.example.com`.
	12	- An SSH key pair. The public half goes in the launch form and in the file; keep
	13	the private half where you keep keys.
c1edfd3c Keenan Nemetz 3d ago	14	- The URL of a Vole `.deb` for `amd64`, from
b7396a11 Keenan Nemetz 6h ago	15	[Vole's releases](https://rodent.software/vole/releases).
b8e7a567 Keenan Nemetz 3d ago	16
942c93cd Keenan Nemetz 3d ago	17	## Render the first-boot file
b8e7a567 Keenan Nemetz 3d ago	18
942c93cd Keenan Nemetz 3d ago	19	From a clone of the Vole repository, on your own computer:
b8e7a567 Keenan Nemetz 3d ago	20
b8e7a567 Keenan Nemetz 3d ago	21	```sh
942c93cd Keenan Nemetz 3d ago	22	cd deploy/cloud-init
	23
	24	HOSTNAME=forge.example.com \
	25	ADMIN_ACCOUNT=admin \
	26	ADMIN_EMAIL=you@example.com \
	27	ADMIN_SSH_KEY="$(cat ~/.ssh/id_ed25519.pub)" \
b7396a11 Keenan Nemetz 6h ago	28	VOLE_PACKAGE_URL=https://rodent.software/vole/releases/v0.2.0/artifacts/vole_0.2.0-1_amd64.deb \
942c93cd Keenan Nemetz 3d ago	29	./render.sh > user-data.yaml
b8e7a567 Keenan Nemetz 3d ago	30	```
b8e7a567 Keenan Nemetz 3d ago	31
942c93cd Keenan Nemetz 3d ago	32	Open `user-data.yaml` before you paste it. It is the whole setup, and it is the
942c93cd Keenan Nemetz 3d ago	33	last chance to notice a wrong account name: names are permanent.
b8e7a567 Keenan Nemetz 3d ago	34
942c93cd Keenan Nemetz 3d ago	35	## Create the security group and the instance
b8e7a567 Keenan Nemetz 3d ago	36
942c93cd Keenan Nemetz 3d ago	37	In the EC2 console, Launch instance:
	38
	39	\| Field \| What to choose \|
	40	\|---\|---\|
	41	\| Name \| `vole` \|
	42	\| AMI \| Ubuntu Server 24.04 LTS (HVM), SSD Volume Type, published by Canonical \|
	43	\| Instance type \| `t3.medium` — 2 vCPU, 4 GB. Raise it if you expect big pushes or LFS \|
	44	\| Key pair \| yours — the same one you put in the file \|
	45	\| Network \| the default VPC's public subnet, with auto-assign public IPv4 enabled. Without a public address the instance cannot fetch its package \|
	46	\| Storage \| 40 GiB gp3, encrypted \|
	47	\| Advanced details → User data \| paste the contents of `user-data.yaml` \|
	48
	49	When it asks for a security group, create one with these inbound rules. Anything
	50	else can stay closed; the instance dials out for its package, its certificate, and
	51	updates:
	52
	53	\| Type \| Protocol \| Port \| Source \|
	54	\|---\|---\|---\|---\|
	55	\| SSH \| tcp \| 22 \| your team's addresses, for shell access \|
	56	\| Custom TCP \| tcp \| 2222 \| your team's addresses. This is Git over SSH, the write transport \|
	57	\| HTTP \| tcp \| 80 \| anywhere, for the certificate challenge \|
	58	\| HTTPS \| tcp \| 443 \| anywhere \|
	59
	60	Restricting 2222 to your team is the cheapest way to keep the write side private.
	61	If you leave it open, Vole still authenticates every connection by key.
	62
	63	An Elastic IP is optional. It keeps the address after a stop and start, which
	64	saves one DNS edit. Both the host name in `public_url` and the SSH host key
	65	clients pin survive an address change, so it is convenience rather than
	66	correctness.
	67
	68	## Point the name at it
	69
	70	Create an `A` record for `forge.example.com` pointing at the instance's public IPv4
	71	address — in Route 53, or wherever the name lives. Vole cannot obtain a
	72	certificate for a name that does not resolve to it yet, and it retries, so a record
	73	created a few minutes after the instance is fine.
	74
	75	## Check it works
	76
	77	Open `https://forge.example.com`. The first request may take a few seconds while
	78	the certificate is issued; if it fails, wait a minute and reload.
b8e7a567 Keenan Nemetz 3d ago	79
942c93cd Keenan Nemetz 3d ago	80	Issue a passkey for the admin account from your laptop:
b8e7a567 Keenan Nemetz 3d ago	81
	82	```sh
	83	vole admin --remote ssh://git@forge.example.com:2222 account invite admin
	84	```
	85
942c93cd Keenan Nemetz 3d ago	86	Then create a repository, and clone it:
	87
	88	```sh
	89	vole admin --remote ssh://git@forge.example.com:2222 repo create demo --owner admin
	90	vole admin --remote ssh://git@forge.example.com:2222 acl set-default-role demo read
	91	git clone ssh://git@forge.example.com:2222/demo.git
	92	```
	93
	94	## Adding a CI runner
	95
	96	Launch a second instance the same way, with a security group that allows only 22
	97	from your addresses, and give it the runner's file:
	98
	99	```sh
	100	./render.sh runner > runner-user-data.yaml # FORGE_HOST=forge.example.com and VOLE_PACKAGE_URL
	101	```
	102
	103	It needs one more step per repository before it takes work; see
	104	[CI runners](runner.md).
	105
b8e7a567 Keenan Nemetz 3d ago	106	## The settings worth changing
b8e7a567 Keenan Nemetz 3d ago	107
942c93cd Keenan Nemetz 3d ago	108	The values you pass to `render.sh`. Everything else has a working default.
b8e7a567 Keenan Nemetz 3d ago	109
942c93cd Keenan Nemetz 3d ago	110	\| Variable \| Default \| What it does \|
b8e7a567 Keenan Nemetz 3d ago	111	\|---\|---\|---\|
942c93cd Keenan Nemetz 3d ago	112	\| `HOSTNAME` \| required \| The name the instance answers on. It becomes `public_url`, and passkeys bind to it \|
	113	\| `ADMIN_ACCOUNT` \| required \| The first account, made an instance admin. Permanent \|
	114	\| `ADMIN_SSH_KEY` \| required \| That account's public key \|
	115	\| `VOLE_PACKAGE_URL` \| required \| The `.deb` for the machine's architecture \|
	116	\| `ADMIN_EMAIL` \| empty \| Contact address for the certificate authority \|
	117	\| `INSTANCE_NAME` \| `Vole` \| What the landing page calls this forge \|
	118	\| `TLS_MODE` \| `acme` \| `proxy` leaves TLS to a proxy you run, and serves plain HTTP on loopback \|
b8e7a567 Keenan Nemetz 3d ago	119
	120	## If something is not right
	121
942c93cd Keenan Nemetz 3d ago	122	- Everything times out. The security group has no inbound rule for the port,
942c93cd Keenan Nemetz 3d ago	123	or the instance has no public IPv4 address.
b8e7a567 Keenan Nemetz 3d ago	124	- The browser shows a certificate warning. DNS is not answering with the
942c93cd Keenan Nemetz 3d ago	125	instance's address yet, or ports 80 and 443 are blocked. Check
942c93cd Keenan Nemetz 3d ago	126	`dig +short forge.example.com`, then `journalctl -u vole \| grep -i acme`.
b8e7a567 Keenan Nemetz 3d ago	127	- The instance is up but the forge is not. First-boot output is in
942c93cd Keenan Nemetz 3d ago	128	`/var/log/vole-first-boot.log`; the service log is `journalctl -u vole` through
	129	the EC2 console or Systems Manager. The usual cause is a package URL that 404s
	130	or is for the other architecture.
	131	- Pushing is refused. `vole whoami --remote ssh://git@forge.example.com:2222`
	132	says which account your key is; if it is not the one you expected, the key was
	133	not the one in `user-data.yaml`.
b8e7a567 Keenan Nemetz 3d ago	134
	135	## Next
	136
942c93cd Keenan Nemetz 3d ago	137	- [Deploying Vole](README.md) — what first boot does, backups, and upgrades
b8e7a567 Keenan Nemetz 3d ago	138	- [Packages](../packaging.md) — the `.deb`, the unit file, and upgrades on the machine
b8e7a567 Keenan Nemetz 3d ago	139	- [Accounts and access](../accounts-and-access.md) — the first accounts, roles, and passkeys