Skip to content

Commit dd6da87

Browse files
joereg4joereg4
committed
feat: add Nix Cache documentation to mkdocs and README
1 parent a720562 commit dd6da87

File tree

3 files changed

+192
-0
lines changed

3 files changed

+192
-0
lines changed

‎nix/docs/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ learn how to play with `postgres` in the [build guide](./build-postgres.md).
1919
- **[Use direnv](./use-direnv.md)** - Development environment with direnv
2020
- **[Pre-commit Hooks](./pre-commit-hooks.md)** - Automatic formatting and code checks before commits
2121
- **[Nix Formatter](./nix-formatter.md)** - Code formatting with treefmt
22+
- **[Nix Cache](./nix-cache.md)** - Understanding and using the Nix binary cache system
2223

2324
## Package Management
2425

‎nix/docs/nix-cache.md‎

Lines changed: 190 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,190 @@
1+
# Nix Cache Documentation
2+
3+
This document explains the Nix binary cache system used in the Supabase PostgreSQL project to speed up builds and share pre-built artifacts.
4+
5+
## What is the Nix Cache?
6+
7+
The Nix cache is a binary cache that stores pre-built Nix packages, allowing developers to download pre-compiled artifacts instead of building them from source. This significantly speeds up development and CI builds.
8+
9+
## Cache Configuration
10+
11+
The project uses a custom Nix binary cache hosted on AWS S3:
12+
13+
- **Cache URL**: `https://nix-postgres-artifacts.s3.amazonaws.com`
14+
- **Primary Cache**: `https://cache.nixos.org` (upstream Nix cache)
15+
- **Trusted Public Key**: `nix-postgres-artifacts:dGZlQOvKcNEjvT7QEAJbcV6b6uk7VF/hWMjhYleiaLI=%`
16+
17+
## How It Works
18+
19+
### 1. Cache Substituters
20+
21+
The cache is configured with two substituters:
22+
23+
```bash
24+
substituters = https://cache.nixos.org https://nix-postgres-artifacts.s3.amazonaws.com
25+
```
26+
27+
This means Nix will:
28+
1. First check the upstream Nix cache (`cache.nixos.org`)
29+
2. Then check the Supabase-specific cache (`nix-postgres-artifacts.s3.amazonaws.com`)
30+
31+
### 2. Trusted Public Keys
32+
33+
```bash
34+
trusted-public-keys = nix-postgres-artifacts:dGZlQOvKcNEjvT7QEAJbcV6b6uk7VF/hWMjhYleiaLI=% cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=
35+
```
36+
37+
These keys ensure that only trusted, signed artifacts are downloaded from the caches.
38+
39+
### 3. Post-Build Hook
40+
41+
The cache includes a post-build hook that automatically uploads newly built packages to the cache:
42+
43+
```bash
44+
post-build-hook = /etc/nix/upload-to-cache.sh
45+
```
46+
47+
## Where Cache is Configured
48+
49+
The cache configuration is duplicated across multiple files in the project:
50+
51+
### CI/CD Workflows
52+
- `.github/workflows/nix-build.yml` - Main build workflow
53+
- `.github/workflows/ami-release-nix.yml` - AMI release workflow
54+
55+
### Docker Images
56+
- `docker/nix/Dockerfile` - Nix Docker image
57+
- `Dockerfile-15`, `Dockerfile-17`, `Dockerfile-orioledb-17` - PostgreSQL Docker images
58+
59+
### Provisioning Scripts
60+
- `scripts/nix-provision.sh` - Local provisioning
61+
- `ebssurrogate/scripts/qemu-bootstrap-nix.sh` - QEMU bootstrap
62+
- `ansible/files/admin_api_scripts/pg_upgrade_scripts/initiate.sh` - Upgrade scripts
63+
64+
## Using the Cache Locally
65+
66+
### Automatic Configuration
67+
68+
The cache is automatically configured when you:
69+
70+
1. **Enter the development shell**:
71+
```bash
72+
nix develop
73+
```
74+
75+
2. **Run CI workflows** - Cache is configured automatically
76+
77+
3. **Use Docker images** - Cache is pre-configured
78+
79+
### Manual Configuration
80+
81+
If you need to configure the cache manually, add these lines to your `~/.config/nix/nix.conf`:
82+
83+
```bash
84+
substituters = https://cache.nixos.org https://nix-postgres-artifacts.s3.amazonaws.com
85+
trusted-public-keys = nix-postgres-artifacts:dGZlQOvKcNEjvT7QEAJbcV6b6uk7VF/hWMjhYleiaLI=% cache.nixos.org-1:6NCHdD59X431o0gWypbMrAURkbJ16ZPMQFGspcDShjY=
86+
```
87+
88+
### Verifying Cache Usage
89+
90+
You can verify that the cache is working by checking the build logs:
91+
92+
```bash
93+
# Look for cache hits in build output
94+
nix build .#psql_15/bin --verbose
95+
96+
# Check cache status
97+
nix show-config | grep substituters
98+
```
99+
100+
## Cache Benefits
101+
102+
### For Developers
103+
- **Faster builds** - Pre-built packages download instead of compiling
104+
- **Consistent environments** - Same artifacts across different machines
105+
- **Reduced bandwidth** - Only download what's needed
106+
107+
### For CI/CD
108+
- **Faster CI runs** - Builds complete in minutes instead of hours
109+
- **Reduced resource usage** - Less CPU and memory consumption
110+
- **Better reliability** - Fewer build failures due to compilation issues
111+
112+
## Troubleshooting
113+
114+
### Cache Not Working
115+
116+
If you're not getting cache hits:
117+
118+
1. **Check configuration**:
119+
```bash
120+
nix show-config | grep substituters
121+
```
122+
123+
2. **Verify network access**:
124+
```bash
125+
curl -I https://nix-postgres-artifacts.s3.amazonaws.com
126+
```
127+
128+
3. **Check trusted keys**:
129+
```bash
130+
nix show-config | grep trusted-public-keys
131+
```
132+
133+
### Cache Misses
134+
135+
If you're seeing cache misses for packages that should be cached:
136+
137+
1. **Check if the package was recently built** - New packages may not be cached yet
138+
2. **Verify the package hash** - Different inputs produce different hashes
139+
3. **Check CI logs** - Ensure the post-build hook is working
140+
141+
### Network Issues
142+
143+
If you're having network issues with the cache:
144+
145+
1. **Try the upstream cache only**:
146+
```bash
147+
nix build .#psql_15/bin --substituters https://cache.nixos.org
148+
```
149+
150+
2. **Disable cache temporarily**:
151+
```bash
152+
nix build .#psql_15/bin --no-substituters
153+
```
154+
155+
## Cache Management
156+
157+
### Uploading to Cache
158+
159+
The cache is automatically populated by:
160+
161+
1. **CI builds** - GitHub Actions upload successful builds
162+
2. **Post-build hooks** - Automatic upload after local builds
163+
3. **Manual uploads** - Using `nix copy` command
164+
165+
### Cache Contents
166+
167+
The cache contains:
168+
- **PostgreSQL binaries** (15, 17, orioledb-17)
169+
- **Extension packages** (all 50+ extensions)
170+
- **Development tools** (build tools, test frameworks)
171+
- **Dependencies** (libraries, compilers, etc.)
172+
173+
## Security
174+
175+
The cache uses cryptographic signatures to ensure:
176+
- **Integrity** - Packages haven't been tampered with
177+
- **Authenticity** - Packages come from trusted sources
178+
- **Reproducibility** - Same inputs produce same outputs
179+
180+
## Related Documentation
181+
182+
- [Development Workflow](./development-workflow.md) - Complete development process
183+
- [Build PostgreSQL](./build-postgres.md) - Building PostgreSQL from source
184+
- [Nix Directory Structure](./nix-directory-structure.md) - Project structure overview
185+
186+
## References
187+
188+
- [Nix Binary Cache Documentation](https://nixos.org/manual/nix/stable/package-management/binary-cache.html)
189+
- [Nix Substituters](https://nixos.org/manual/nix/stable/command-ref/conf-file.html#conf-substituters)
190+
- [Nix Trusted Public Keys](https://nixos.org/manual/nix/stable/command-ref/conf-file.html#conf-trusted-public-keys)

‎nix/mkdocs.yml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@ nav:
1919
- Use direnv: use-direnv.md
2020
- Code Formatter: nix-formatter.md
2121
- Pre-commit Hooks: pre-commit-hooks.md
22+
- Nix Cache: nix-cache.md
2223
- Documentation: documentation.md
2324
- Package Management:
2425
- Adding New Packages: adding-new-package.md

0 commit comments

Comments
 (0)