fabrica / docs / deployment.md

1 # Deployment
2
3 fabrica is one binary, one config file, one data directory. It needs the `git`
4 binary (≥ 2.41) on `PATH` at runtime — every deployment path below guarantees it.
5
6 ## Configuration
7
8 Copy `fabrica.example.toml`, edit it, and point the binary at it with `--config`
9 (or place it at `/etc/fabrica/fabrica.toml` or `$XDG_CONFIG_HOME/fabrica/`). Every
10 key can be overridden by an environment variable `FABRICA__<SECTION>__<KEY>`
11 (double underscores nest), and any `*_file` key reads its value from a file (for
12 agenix / systemd-creds / Docker secrets). Validate with `fabrica config check`;
13 inspect the merged result (secrets redacted) with `fabrica config show`.
14
15 On first run fabrica generates its HS256 secret (`auth.secret_file`, default
16 `{data_dir}/secret`, mode 0600) and its SSH host key (`ssh.host_key_path`).
17
18 ## Docker / Compose
19
20 `docker compose up` builds the image (`Dockerfile`) and starts fabrica on `:8080`
21 (HTTP) and `:2222` (SSH), with named volumes for the data and repos. The default
22 database is SQLite; add `--profile postgres` to bring up Postgres and point
23 `FABRICA__DATABASE__URL` at it.
24
25 The image is multi-stage: the builder compiles with `--features vendored` (libgit2
26 is statically linked), so the runtime (`debian:stable-slim`) needs only `git`,
27 `ca-certificates`, `tini`, and `libssl3`. It runs as a non-root user, `git
28 --version` is verified at build time, and the health check is `fabrica doctor
29 --quiet`.
30
31 ### Reverse proxy — read this
32
33 A proxy in front **MUST NOT buffer** the git pack routes, or clones stall. For
34 nginx:
35
36 ```nginx
37 location / {
38     proxy_pass http://127.0.0.1:8080;
39     proxy_http_version 1.1;
40     proxy_buffering off;          # critical for /info/refs and /git-upload-pack
41     proxy_request_buffering off;
42     proxy_read_timeout 3600s;
43 }
44 ```
45
46 Set `server.behind_proxy = true` so `X-Forwarded-For`/`-Proto` are trusted, and
47 `auth.cookie_secure = true` once you terminate TLS at the proxy.
48
49 ## NixOS
50
51 The flake exposes `nixosModules.default`:
52
53 ```nix
54 {
55   inputs.fabrica.url = "github:you/fabrica";
56   # …
57   nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
58     modules = [
59       fabrica.nixosModules.default
60       {
61         services.fabrica = {
62           enable = true;
63           openFirewall = true;
64           environmentFile = "/run/secrets/fabrica.env";   # FABRICA__* secrets
65           settings = {
66             instance.url = "https://git.example.com";
67             instance.name = "our forge";
68             server.port = 8080;
69             ssh.port = 2222;
70             database.url = "sqlite:///var/lib/fabrica/fabrica.db";
71           };
72         };
73       }
74     ];
75   };
76 }
77 ```
78
79 The module renders `settings` to a TOML file, runs a hardened `systemd` unit
80 (`DynamicUser` off, `StateDirectory=fabrica`, `ProtectSystem=strict`,
81 `NoNewPrivileges`, `CAP_NET_BIND_SERVICE` only when a privileged port is
82 configured), and opens the firewall when asked. The package wraps the binary with
83 `git` on `PATH`.
84
85 ## Nix container
86
87 `nix build .#container` produces an OCI image (`dockerTools.buildLayeredImage`)
88 with `git` and `ca-certificates` in the closure — a Nix-native alternative to the
89 `Dockerfile`. Load it with `docker load < result`.
90
91 ## First user
92
93 There is no web sign-up. Create the first account from the CLI (the same binary):
94
95 ```sh
96 fabrica --config /etc/fabrica/fabrica.toml user add alice alice@example.com --admin
97 # prints an activation link; or set a password directly:
98 fabrica --config /etc/fabrica/fabrica.toml user passwd alice
99 fabrica --config /etc/fabrica/fabrica.toml key add --type ssh alice @~/.ssh/id_ed25519.pub
100 ```
101
102 Run `fabrica doctor` to confirm git, the config, and the database are healthy.
1	# Deployment
2
3	fabrica is one binary, one config file, one data directory. It needs the `git`
4	binary (≥ 2.41) on `PATH` at runtime — every deployment path below guarantees it.
5
6	## Configuration
7
8	Copy `fabrica.example.toml`, edit it, and point the binary at it with `--config`
9	(or place it at `/etc/fabrica/fabrica.toml` or `$XDG_CONFIG_HOME/fabrica/`). Every
10	key can be overridden by an environment variable `FABRICA__<SECTION>__<KEY>`
11	(double underscores nest), and any `*_file` key reads its value from a file (for
12	agenix / systemd-creds / Docker secrets). Validate with `fabrica config check`;
13	inspect the merged result (secrets redacted) with `fabrica config show`.
14
15	On first run fabrica generates its HS256 secret (`auth.secret_file`, default
16	`{data_dir}/secret`, mode 0600) and its SSH host key (`ssh.host_key_path`).
17
18	## Docker / Compose
19
20	`docker compose up` builds the image (`Dockerfile`) and starts fabrica on `:8080`
21	(HTTP) and `:2222` (SSH), with named volumes for the data and repos. The default
22	database is SQLite; add `--profile postgres` to bring up Postgres and point
23	`FABRICA__DATABASE__URL` at it.
24
25	The image is multi-stage: the builder compiles with `--features vendored` (libgit2
26	is statically linked), so the runtime (`debian:stable-slim`) needs only `git`,
27	`ca-certificates`, `tini`, and `libssl3`. It runs as a non-root user, `git
28	--version` is verified at build time, and the health check is `fabrica doctor
29	--quiet`.
30
31	### Reverse proxy — read this
32
33	A proxy in front MUST NOT buffer the git pack routes, or clones stall. For
34	nginx:
35
36	```nginx
37	location / {
38	proxy_pass http://127.0.0.1:8080;
39	proxy_http_version 1.1;
40	proxy_buffering off; # critical for /info/refs and /git-upload-pack
41	proxy_request_buffering off;
42	proxy_read_timeout 3600s;
43	}
44	```
45
46	Set `server.behind_proxy = true` so `X-Forwarded-For`/`-Proto` are trusted, and
47	`auth.cookie_secure = true` once you terminate TLS at the proxy.
48
49	## NixOS
50
51	The flake exposes `nixosModules.default`:
52
53	```nix
54	{
55	inputs.fabrica.url = "github:you/fabrica";
56	# …
57	nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
58	modules = [
59	fabrica.nixosModules.default
60	{
61	services.fabrica = {
62	enable = true;
63	openFirewall = true;
64	environmentFile = "/run/secrets/fabrica.env"; # FABRICA__* secrets
65	settings = {
66	instance.url = "https://git.example.com";
67	instance.name = "our forge";
68	server.port = 8080;
69	ssh.port = 2222;
70	database.url = "sqlite:///var/lib/fabrica/fabrica.db";
71	};
72	};
73	}
74	];
75	};
76	}
77	```
78
79	The module renders `settings` to a TOML file, runs a hardened `systemd` unit
80	(`DynamicUser` off, `StateDirectory=fabrica`, `ProtectSystem=strict`,
81	`NoNewPrivileges`, `CAP_NET_BIND_SERVICE` only when a privileged port is
82	configured), and opens the firewall when asked. The package wraps the binary with
83	`git` on `PATH`.
84
85	## Nix container
86
87	`nix build .#container` produces an OCI image (`dockerTools.buildLayeredImage`)
88	with `git` and `ca-certificates` in the closure — a Nix-native alternative to the
89	`Dockerfile`. Load it with `docker load < result`.
90
91	## First user
92
93	There is no web sign-up. Create the first account from the CLI (the same binary):
94
95	```sh
96	fabrica --config /etc/fabrica/fabrica.toml user add alice alice@example.com --admin
97	# prints an activation link; or set a password directly:
98	fabrica --config /etc/fabrica/fabrica.toml user passwd alice
99	fabrica --config /etc/fabrica/fabrica.toml key add --type ssh alice @~/.ssh/id_ed25519.pub
100	```
101
102	Run `fabrica doctor` to confirm git, the config, and the database are healthy.