1open module Service
2
3import "site.pkl" as site
4
5const nomadHostPort = "{{ if regexMatch \":\" .Address }}[{{ .Address }}]{{ else }}{{ .Address }}{{ end }}:{{ .Port }}"
6
7/// One HTTP listener and its public route.
8class Http {
9 containerPort: UInt16
10 hostPort: UInt16?
11 loopback: Boolean = false
12 subdomain: String?
13 authRole: String?
14 /// Backend header set from the authenticated OIDC preferred username.
15 userHeader: String?
16 /// Identity headers copied from a valid SSO session; anonymous requests continue.
17 identityHeaders: Mapping<String, String> = new {}
18 /// Set X-Real-Ip from Caddy's observed client address before proxying.
19 forwardRealIp: Boolean = false
20 /// Require HTTPS when browsers send cookies issued by this route.
21 secureCookies: Boolean = false
22 /// Generated secret whose value becomes the private proxy header name.
23 identityProofSecret: String?
24 /// Additional hosts routed to this container without SSO headers.
25 plainHostnames: Listing<String> = new {}
26 hostname: String? = read?("prop:hostname") ?? if (subdomain != null) "\(subdomain).\(site.domain)" else null
27 tlsInternal: Boolean = site.tlsInternal
28 checkPath: String = "/"
29 /// Internal Prometheus endpoint collected by the home server dashboard.
30 metricsPath: String?
31 checkHeaders: Mapping<String, String> = new {}
32 /// API paths authenticated by a sibling task, bypassing the browser login proxy.
33 apiPaths: Mapping<String, String> = new {}
34 /// Request path to a file or directory in this service's folder.
35 overrideFiles: Mapping<String, String> = new {}
36 /// HTML inserted before </head> for the listed page paths.
37 headHtml: Mapping<String, String> = new {}
38}
39
40/// One TCP listener published through Nomad.
41class Tcp {
42 name: String
43 containerPort: UInt16
44 hostPort: UInt16?
45 loopback: Boolean = true
46}
47
48/// A container mount, keyed by its absolute path inside the container.
49class Volume {
50 /// Host source; absent means the same path beneath this service's data root.
51 src: String?
52 /// File or directory relative to this service's assets folder; copied into a read-only mount.
53 config: String?
54 readOnly: Boolean = config != null
55}
56
57/// A persistent value generated when the service is first provisioned.
58class GeneratedSecret {
59 bytes: Int(isBetween(16, 128)) = 32
60}
61
62/// Provider-owned resource request; the alias names its allocated secret.
63open class Requirement {
64 alias: String
65 fixed provider: String
66 fixed kind: String
67}
68
69/// One Podman task. A service can contain one or several of these.
70class Container {
71 /// Use either an image or a build directory in this service's release folder.
72 image: String?
73 build: String?
74 entrypoint: String?
75 http: Http?
76 tcp: Listing<Tcp> = new {}
77 volumes: Mapping<String, Volume> = new {}
78 /// Podman tmpfs mounts for data that must not persist in service storage.
79 tmpfs: Listing<String> = new {}
80 /// `${secret.own.key}` and `${secret.alias.key}` resolve from Nomad variables.
81 env: Mapping<String, String> = new {}
82 /// Nomad template for environment values resolved after allocation.
83 envTemplate: String?
84 /// Nomad templates rendered privately and mounted read-only at absolute container paths.
85 secretFiles: Mapping<String, String> = new {}
86 args: Listing<String> = new {}
87 capAdd: Listing<String> = new {}
88 readOnlyRoot: Boolean = false
89 killTimeout: String?
90 devices: Listing<String> = new {}
91 extraHosts: Listing<String> = new {}
92 hostNetwork: Boolean = false
93 imageUser: Boolean = false
94 /// Prestart tasks finish first; prestart sidecars stay up for the main tasks.
95 lifecycle: "main"|"prestart"|"prestartSidecar" = "main"
96 rootGroup: Boolean = false
97 cpu: Int = 200
98 memory: Int = 512
99}
100
101/// Stable internal ID supplied from the service definition name by the caller.
102id: String = read?("prop:serviceId")
103/// Stable numeric owner assigned by the deployment tool.
104uid: Int = read("prop:uid").toInt()
105/// Name shown in the management UI and service listings.
106name: String
107tagline: String = ""
108launcher: Boolean = true
109/// Discovery group; absent uses the public route's auth role.
110access: String?
111/// Allows site-specific services to stay out of deployments where they would cause side effects.
112enabled: Boolean = true
113/// Simple replaces one allocation; overlapped runs a canary alongside it.
114rollout: String = "simple"
115/// Fresh previews create empty storage and new secrets instead of forking production.
116stageIsolation: "clone"|"fresh" = "clone"
117/// Include the managed dataset in deployment backup snapshots.
118snapshots: Boolean = true
119/// Time allowed for a new allocation to pass its service checks.
120healthyDeadline: String?
121/// Delay before persistent health-check failures may restart a running allocation.
122healthRestartGrace: String?
123/// Repeatable service configuration run after a healthy deployment.
124setup: String?
125/// Service-owned data preparation before its container starts.
126prepare: String?
127/// Handler for input requests owned by this service.
128provide: String?
129
130/// Use this for one container; it becomes the "app" task in the output.
131container: Container?
132
133/// Use this instead of `container` when the service has named tasks.
134containers: Mapping<String, Container>?
135
136secrets: Mapping<String, GeneratedSecret> = new {}
137/// Secret names supplied from outside the release, in import-file line order.
138requiredSecrets: Listing<String> = new {}
139requirements: Listing<Requirement> = new {}
140/// Service startup dependency with no resource to allocate.
141dependsOn: Listing<String> = new {}
142/// Resource service.name emitted by this app's trace exporter.
143traceServiceName: String?
144/// Metrics sent by the app over OTLP instead of a Prometheus HTTP endpoint.
145metricsPushed: Boolean = false
146
147local deploymentContainers: Mapping<String, Container> =
148 if (!enabled)
149 new Mapping {}
150 else if (container != null && containers != null)
151 throw("Declare either container or containers, not both")
152 else if (container != null)
153 new Mapping { ["app"] = container!! }
154 else if (containers != null && !containers!!.isEmpty)
155 containers!!
156 else if (!requirements.isEmpty)
157 new Mapping {}
158 else
159 throw("Declare a container or an input")
160
161local vmStartupGrace: String? = if (read?("env:SNOWGLOBE_VM_ACCEL") == "qemu") "60m" else null
162
163output {
164 renderer = new JsonRenderer {}
165 value = new {
166 id = module.id
167 name = module.name
168 tagline = module.tagline
169 launcher = module.launcher
170 access = module.access
171 rollout = module.rollout
172 stageIsolation = module.stageIsolation
173 snapshots = module.snapshots
174 healthyDeadline = vmStartupGrace ?? module.healthyDeadline
175 healthRestartGrace = vmStartupGrace ?? module.healthRestartGrace
176 hostRoot = "\(site.root)/prod/\(module.id)"
177 stagingRoot = "\(site.root)/staging"
178 pool = site.pool
179 cloverRoot = site.cloverRoot
180 cloverGid = site.cloverGid
181 mediaRoot = site.mediaRoot
182 ownerEmail = site.ownerEmail
183 containers = deploymentContainers
184 setup = module.setup
185 prepare = module.prepare
186 provide = module.provide
187 // External mounts do not require this service's dataset.
188 hasManagedVolumes = deploymentContainers.toMap().values.any((task) ->
189 task.volumes.toMap().values.any((volume) -> volume.src == null && volume.config == null))
190 secrets = module.secrets
191 requiredSecrets = module.requiredSecrets
192 requirements = module.requirements
193 dependsOn = module.dependsOn
194 traceServiceName = module.traceServiceName
195 metricsPushed = module.metricsPushed
196 }
197}