Skip to content

Commit 6c33314

Browse files
rpulsrpuls
committed
refactor(deploy): standardize Dockerfile-based image pinning, adopt Valkey naming, and align docs/CI
1 parent 3fbe42d commit 6c33314

25 files changed

Lines changed: 346 additions & 192 deletions

‎.env.example‎

Lines changed: 0 additions & 7 deletions
This file was deleted.

‎.github/dependabot.yml‎

Lines changed: 125 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,125 @@
1+
version: 2
2+
updates:
3+
- package-ecosystem: "npm"
4+
directory: "/"
5+
schedule:
6+
interval: "weekly"
7+
day: "monday"
8+
time: "06:00"
9+
timezone: "Europe/Amsterdam"
10+
open-pull-requests-limit: 5
11+
groups:
12+
root-npm:
13+
patterns:
14+
- "*"
15+
16+
- package-ecosystem: "npm"
17+
directory: "/site"
18+
schedule:
19+
interval: "weekly"
20+
day: "monday"
21+
time: "06:15"
22+
timezone: "Europe/Amsterdam"
23+
open-pull-requests-limit: 5
24+
groups:
25+
site-npm:
26+
patterns:
27+
- "*"
28+
29+
- package-ecosystem: "npm"
30+
directory: "/apps/homepage/config-generator"
31+
schedule:
32+
interval: "weekly"
33+
day: "monday"
34+
time: "06:30"
35+
timezone: "Europe/Amsterdam"
36+
open-pull-requests-limit: 5
37+
groups:
38+
homepage-config-generator:
39+
patterns:
40+
- "*"
41+
42+
- package-ecosystem: "docker"
43+
directory: "/deploy/vps"
44+
schedule:
45+
interval: "weekly"
46+
day: "monday"
47+
time: "06:45"
48+
timezone: "Europe/Amsterdam"
49+
open-pull-requests-limit: 10
50+
groups:
51+
docker-compose-images:
52+
patterns:
53+
- "*"
54+
55+
- package-ecosystem: "docker"
56+
directory: "/apps/homepage"
57+
schedule:
58+
interval: "weekly"
59+
day: "monday"
60+
time: "07:00"
61+
timezone: "Europe/Amsterdam"
62+
open-pull-requests-limit: 10
63+
64+
- package-ecosystem: "docker"
65+
directory: "/apps/caddy"
66+
schedule:
67+
interval: "weekly"
68+
day: "monday"
69+
time: "07:03"
70+
timezone: "Europe/Amsterdam"
71+
open-pull-requests-limit: 10
72+
73+
- package-ecosystem: "docker"
74+
directory: "/apps/immich"
75+
schedule:
76+
interval: "weekly"
77+
day: "monday"
78+
time: "07:05"
79+
timezone: "Europe/Amsterdam"
80+
open-pull-requests-limit: 10
81+
82+
- package-ecosystem: "docker"
83+
directory: "/apps/onlyoffice"
84+
schedule:
85+
interval: "weekly"
86+
day: "monday"
87+
time: "07:20"
88+
timezone: "Europe/Amsterdam"
89+
open-pull-requests-limit: 10
90+
91+
- package-ecosystem: "docker"
92+
directory: "/apps/radicale"
93+
schedule:
94+
interval: "weekly"
95+
day: "monday"
96+
time: "07:25"
97+
timezone: "Europe/Amsterdam"
98+
open-pull-requests-limit: 10
99+
100+
- package-ecosystem: "docker"
101+
directory: "/apps/seafile"
102+
schedule:
103+
interval: "weekly"
104+
day: "monday"
105+
time: "07:30"
106+
timezone: "Europe/Amsterdam"
107+
open-pull-requests-limit: 10
108+
109+
- package-ecosystem: "docker"
110+
directory: "/apps/stirling-pdf"
111+
schedule:
112+
interval: "weekly"
113+
day: "monday"
114+
time: "07:35"
115+
timezone: "Europe/Amsterdam"
116+
open-pull-requests-limit: 10
117+
118+
- package-ecosystem: "docker"
119+
directory: "/apps/vaultwarden"
120+
schedule:
121+
interval: "weekly"
122+
day: "monday"
123+
time: "07:40"
124+
timezone: "Europe/Amsterdam"
125+
open-pull-requests-limit: 10

‎.github/workflows/ci.yml‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
name: CI
2+
3+
on:
4+
pull_request:
5+
push:
6+
branches:
7+
- main
8+
9+
permissions:
10+
contents: read
11+
12+
jobs:
13+
docs-build:
14+
name: Docs Build
15+
runs-on: ubuntu-latest
16+
defaults:
17+
run:
18+
working-directory: site
19+
steps:
20+
- name: Checkout
21+
uses: actions/checkout@v4
22+
23+
- name: Setup Node
24+
uses: actions/setup-node@v4
25+
with:
26+
node-version: 20
27+
cache: npm
28+
cache-dependency-path: site/package-lock.json
29+
30+
- name: Install dependencies
31+
run: npm ci
32+
33+
- name: Build docs site
34+
run: npm run build
35+
36+
homepage-config-generator:
37+
name: Homepage Config Generator Build
38+
runs-on: ubuntu-latest
39+
defaults:
40+
run:
41+
working-directory: apps/homepage/config-generator
42+
steps:
43+
- name: Checkout
44+
uses: actions/checkout@v4
45+
46+
- name: Setup Node
47+
uses: actions/setup-node@v4
48+
with:
49+
node-version: 20
50+
cache: npm
51+
cache-dependency-path: apps/homepage/config-generator/package-lock.json
52+
53+
- name: Install dependencies
54+
run: npm ci
55+
56+
- name: Build generator
57+
run: npm run build
58+
59+
compose-validate:
60+
name: Docker Compose Validate
61+
runs-on: ubuntu-latest
62+
steps:
63+
- name: Checkout
64+
uses: actions/checkout@v4
65+
66+
- name: Prepare env files
67+
shell: bash
68+
run: |
69+
cp deploy/vps/.env.example deploy/vps/.env
70+
cp deploy/vps/apps/homepage/.env.example deploy/vps/apps/homepage/.env
71+
cp deploy/vps/apps/seafile/.env.example deploy/vps/apps/seafile/.env
72+
cp deploy/vps/apps/onlyoffice/.env.example deploy/vps/apps/onlyoffice/.env
73+
cp deploy/vps/apps/immich/.env.example deploy/vps/apps/immich/.env
74+
cp deploy/vps/apps/radicale/.env.example deploy/vps/apps/radicale/.env
75+
cp deploy/vps/apps/stirling-pdf/.env.example deploy/vps/apps/stirling-pdf/.env
76+
cp deploy/vps/apps/vaultwarden/.env.example deploy/vps/apps/vaultwarden/.env
77+
78+
- name: Validate compose config
79+
run: docker compose -f deploy/vps/docker-compose.yml --project-directory deploy/vps config -q
80+
81+
shellcheck:
82+
name: Shell Scripts Lint
83+
runs-on: ubuntu-latest
84+
steps:
85+
- name: Checkout
86+
uses: actions/checkout@v4
87+
88+
- name: Run ShellCheck
89+
uses: ludeeus/action-shellcheck@2.0.0
90+
with:
91+
scandir: ./apps

‎AGENTS.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,3 +114,59 @@ For each app page:
114114
- Preserve existing facts; do not drop meaningful technical details.
115115
- Rephrase/move content rather than delete unless it is redundant filler.
116116
- Keep wording concise and direct.
117+
118+
## Container and Versioning Rules
119+
120+
These rules are mandatory for app/service onboarding and version updates.
121+
122+
### Single source of truth for container versions
123+
124+
- Do not write runtime image tags/digests directly in `deploy/vps/docker-compose.yml`.
125+
- `deploy/vps/docker-compose.yml` must use `build:` entries that point to Dockerfiles in `apps/`.
126+
- Pin base images in Dockerfiles with immutable digests (`FROM image@sha256:...`).
127+
- Never use floating tags like `latest` or `release` in runtime Dockerfiles.
128+
129+
### Required Dockerfile layout
130+
131+
For each app, Dockerfiles must live in the app root folder:
132+
133+
- Primary app service: `apps/<app>/Dockerfile`
134+
- Additional services: `apps/<app>/Dockerfile.<service>`
135+
136+
Examples:
137+
138+
- `apps/immich/Dockerfile`
139+
- `apps/immich/Dockerfile.machine-learning`
140+
- `apps/immich/Dockerfile.postgres`
141+
- `apps/immich/Dockerfile.valkey`
142+
- `apps/seafile/Dockerfile`
143+
- `apps/seafile/Dockerfile.mysql`
144+
- `apps/seafile/Dockerfile.memcached`
145+
146+
Do not introduce new canonical Dockerfiles in nested subfolders like `apps/<app>/<service>/Dockerfile`.
147+
148+
### Backward compatibility for existing paths
149+
150+
- Dockerfile paths used by external deploy templates (Railway/Dokploy) are treated as stable API.
151+
- If a path is already used publicly, do not remove or move it in a patch/minor change.
152+
- If a path migration is needed:
153+
- Keep the old Dockerfile as a compatibility stub.
154+
- Add a deprecation comment pointing to the canonical root-level Dockerfile.
155+
- Remove old paths only in a clearly documented breaking release.
156+
157+
### Compose authoring rules when adding a service
158+
159+
When adding a new service to `deploy/vps/docker-compose.yml`:
160+
161+
- Use:
162+
- `build.context: ../../apps/<app>`
163+
- `build.dockerfile: Dockerfile` or `Dockerfile.<service>`
164+
- Do not use direct `image:` references for services managed by this repo.
165+
166+
### Docs and automation updates required with each new service
167+
168+
When adding/changing an app service, also update:
169+
170+
- `apps/<app>/README.md` technical specs (env vars, volumes, healthchecks, dependencies).
171+
- `deploy/vps/apps/<app>/.env.example` when relevant.
172+
- `.github/dependabot.yml` Docker entries for the affected app root directory.

‎apps/caddy/Dockerfile‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
FROM caddy@sha256:c3d7ee5d2b11f9dc54f947f68a734c84e9c9666c92c88a7f30b9cba5da182adb

‎apps/homepage/Dockerfile‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
# ============================================
55
# Stage 1: Build TypeScript Config Generator
66
# ============================================
7-
FROM node:20-alpine AS builder
7+
FROM node@sha256:09e2b3d9726018aecf269bd35325f46bf75046a643a66d28360ec71132750ec8 AS builder
88

99
WORKDIR /build
1010

@@ -20,7 +20,7 @@ RUN npm run build
2020
# ============================================
2121
# Stage 2: Runtime Image
2222
# ============================================
23-
FROM ghcr.io/gethomepage/homepage:latest
23+
FROM ghcr.io/gethomepage/homepage@sha256:0b596092c0b55fe4c65379a428a3fe90bd192f10d1b07d189a34fe5fabe7eedb
2424

2525
# Copy built config generator (only production dependencies needed at runtime)
2626
COPY --from=builder /build/dist /app/config-generator/dist
@@ -38,4 +38,4 @@ RUN chmod +x /entrypoint.sh
3838
EXPOSE 3000
3939

4040
# Use custom entrypoint
41-
ENTRYPOINT ["/entrypoint.sh"]
41+
ENTRYPOINT ["/entrypoint.sh"]

‎apps/immich/Dockerfile‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Immich Server (Platform Deployments)
2+
# Canonical primary Dockerfile for Immich app root.
3+
4+
FROM ghcr.io/immich-app/immich-server@sha256:aa163d2e1cc2b16a9515dd1fef901e6f5231befad7024f093d7be1f2da14341a

apps/immich/machine-learning/Dockerfile renamed to apps/immich/Dockerfile.machine-learning

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
# Immich Machine Learning Service (Platform Deployments)
22
# Stable Railway build target for the Immich ML worker container.
33

4-
FROM ghcr.io/immich-app/immich-machine-learning:release
5-
4+
FROM ghcr.io/immich-app/immich-machine-learning@sha256:b213fa3c82d27a21a299c46ffbb38a091f18384db1ad67d409a3b34fe0fce556

apps/immich/postgres/Dockerfile renamed to apps/immich/Dockerfile.postgres

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,4 @@
11
# Immich PostgreSQL Service (Platform Deployments)
22
# Stable Railway/VPS build target for Immich's vector-enabled Postgres image.
33

4-
FROM ghcr.io/immich-app/postgres:14-vectorchord0.3.0-pgvectors0.2.0
5-
4+
FROM ghcr.io/immich-app/postgres@sha256:c570d9e1c2494f65d2a0a379a7f6df66e8441964254a30aa62cc58e8ebf1dee0

‎apps/immich/Dockerfile.server‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Deprecated compatibility path.
2+
# Canonical file: apps/immich/Dockerfile
3+
4+
FROM ghcr.io/immich-app/immich-server@sha256:aa163d2e1cc2b16a9515dd1fef901e6f5231befad7024f093d7be1f2da14341a

0 commit comments

Comments
 (0)