A production-ready HTTP server starter template built on Echo v5. It provides a modular foundation for Go microservices with structured logging, flexible TLS, and reverse-proxy awareness — without imposing choices about persistence, auth, or business logic.
The compiled binary is named appsvrd (application server daemon).
- Features
- Requirements
- Quick start
- Project layout
- Configuration
- Built-in endpoints
- API specification (OpenAPI 3.0)
- Database (optional)
- Adding a route
- Build tasks
- Rebranding the starter
- Container
- Kubernetes deployment via Helm
- Releases
- License
- Echo v5 HTTP framework with a curated middleware stack (Recover, RequestID, Gzip, structured access log, CORS, security headers)
- Dual-server topology — separate HTTP and HTTPS servers, optional HTTP→HTTPS redirect
- Three TLS modes — static certificate files, ephemeral self-signed (ECDSA P-384), or Let's Encrypt via ACME
autocert - Reverse-proxy aware — configurable trust for direct IP,
X-Real-IP, andX-Forwarded-Forwith CIDR allowlists - Modular routing — composable
Module → Route → Endpointhierarchy with per-module middleware and prefix nesting - Structured logging via zerolog with two independent loggers:
Daemon(lifecycle) andAccess(HTTP) - Layered configuration — YAML/JSON config files plus environment variable overrides (prefix
APP_) - Graceful shutdown on
SIGINT,SIGTERM, andSIGUSR1(Unix) /SIGINT(Windows), with configurable timeout - Cross-platform builds for
linux,darwin,windows×amd64,arm64 - Kubernetes-ready — bundled Helm chart at
charts/go-echo-starter/with optionalServiceMonitor/PodMonitor/ Grafana AlloyPodLogs, structured seccomp at pod and container scope, user-supplied Secret support viaenvFromand TLS volume mounts, and OCI publishing to GHCR - Universal supply-chain attestations — every release artifact and OCI subject (binaries, hash files, helm chart
.tgz, container image, helm OCI artifact, all CycloneDX SBOMs in JSON and XML) carries a GitHub-signed Sigstore attestation verifiable withgh attestation verify
- Go 1.27+
- Task (for the build/dev workflow)
- Docker (optional, for container builds)
# Vendor, lint, and build all platform binaries
task
# Run the daemon locally (builds first)
task run:daemon
# Run all tests with race detector and coverage
task testtask run:daemon binds to 127.0.0.1:8888 (HTTP) and 127.0.0.1:4443 (HTTPS) via the dev overrides in Taskfile.yaml. The binary's own defaults — when run outside the Taskfile — are :8080 (HTTP) and :8443 (HTTPS).
cmd/daemon/ # main package — bootstrap and lifecycle wiring
internal/
application/ # Application, server setup, TLS, proxy, top-level config
api/ # Route module hierarchy (api → v1) + std implementations
router/ # Module/Route/Endpoint interfaces
config/ # YAML/JSON file loader
env/ # Type-safe environment variable parsers
logging/ # Zerolog setup, middleware, named loggers
errors/ # errorx namespaces (FileSystemErrors)
health/ # Per-component health Registry, Report model, Accept-header renderer
openapi/ # OpenAPI 3.0 spec generator + /openapi.{yaml,json} module + optional Swagger UI module
database/ # Optional SQL connection pool (pgx), Goose migrations, Bun ORM
migrations/sql/ # Embedded *.sql migration files
orm/ # Bun ORM singleton + (your) domain models
version/ # Build-time version metadata
charts/
go-echo-starter/ # Helm chart — Chart.yaml, values.yaml, templates/, ci/{default,full}-values.yaml
.github/
workflows/ # CI: PR Formatting, PR Checks (incl. Helm Lint + Helm Install), CodeQL, Deploy Release, reusable callees
docs/ # Workflow naming-standards reference
.releaserc.json # semantic-release configuration (consumed by Deploy Release)
Taskfile.yaml # Build, lint, test, run, container, helm tasks
Dockerfile # Multi-arch container image (consumes bin/)
Configuration is loaded in order: built-in defaults → config file → environment variables.
Looked up under standard search paths (e.g. ./, ~/.appsvr/, /etc/appsvr/) using YAML or JSON.
All keys are prefixed with APP_. Examples:
| Variable | Default | Purpose |
|---|---|---|
APP_DAEMON_LOG_LEVEL |
info |
Daemon log level (trace–fatal) |
APP_DAEMON_LOG_PRETTY_PRINT |
true |
Color console output for daemon log |
APP_DAEMON_LOG_INCLUDE_CALLER |
false |
Include caller file:line in log output |
APP_HTTP_ACCESS_LOG_ENABLED |
false |
Toggle the HTTP access log |
APP_HTTP_ACCESS_LOG_LEVEL |
error |
Access log level |
APP_HTTP_ACCESS_LOG_PRETTY_PRINT |
false |
Color console output |
APP_SERVER_HTTP_PORT |
8080 |
HTTP listener port |
APP_SERVER_HTTP_SHUTDOWN_TIMEOUT |
10s |
Graceful shutdown deadline (HTTP) |
APP_SERVER_HTTP_READ_TIMEOUT |
30s |
Max time to read entire request (HTTP) |
APP_SERVER_HTTP_READ_HEADER_TIMEOUT |
5s |
Max time to read request headers (HTTP) |
APP_SERVER_HTTP_WRITE_TIMEOUT |
30s |
Max time to write response (HTTP) |
APP_SERVER_HTTP_IDLE_TIMEOUT |
120s |
Keep-alive idle timeout (HTTP) |
APP_SERVER_HTTP_MAX_BODY_SIZE |
1MB |
Max request body size; oversize → 413 (HTTP). Accepts B/KB/MB/GB suffixes or bare bytes. |
APP_SERVER_HTTPS_ENABLED |
false |
Enable the TLS server |
APP_SERVER_HTTPS_PORT |
8443 |
HTTPS listener port |
APP_SERVER_HTTPS_HOSTNAME |
— | Hostname presented in self-signed/ACME cert |
APP_SERVER_HTTPS_USE_ACME_ISSUER |
false |
Use Let's Encrypt instead of static certs |
APP_SERVER_HTTPS_SHUTDOWN_TIMEOUT |
10s |
Graceful shutdown deadline (HTTPS) |
APP_SERVER_HTTPS_READ_TIMEOUT |
30s |
Max time to read entire request (HTTPS) |
APP_SERVER_HTTPS_READ_HEADER_TIMEOUT |
5s |
Max time to read request headers (HTTPS) |
APP_SERVER_HTTPS_WRITE_TIMEOUT |
30s |
Max time to write response (HTTPS) |
APP_SERVER_HTTPS_IDLE_TIMEOUT |
120s |
Keep-alive idle timeout (HTTPS) |
APP_SERVER_HTTPS_MAX_BODY_SIZE |
1MB |
Max request body size; oversize → 413 (HTTPS) |
APP_SERVER_CORS_ALLOW_ORIGINS |
(empty — CORS disabled) | Comma-separated list of origins (e.g. https://app.example.com,https://admin.example.com). Empty disables CORS entirely. |
APP_SERVER_CORS_ALLOW_METHODS |
— | Comma-separated method allowlist; defaults to GET/HEAD/PUT/PATCH/POST/DELETE if unset and CORS is enabled. |
APP_SERVER_CORS_ALLOW_HEADERS |
— | Comma-separated request-header allowlist |
APP_SERVER_CORS_ALLOW_CREDENTIALS |
false |
Allow cookies/auth headers in cross-origin requests. Cannot be combined with wildcard origins. |
APP_SERVER_CORS_MAX_AGE |
0 |
Preflight cache lifetime in seconds |
APP_SERVER_SECURITY_HSTS_MAX_AGE |
31536000 |
Strict-Transport-Security max-age (seconds). 0 suppresses the header. Emitted only on TLS requests (or X-Forwarded-Proto: https). |
APP_SERVER_SECURITY_HSTS_EXCLUDE_SUBDOMAINS |
false |
When true, drops the includeSubDomains directive from HSTS. |
APP_SERVER_SECURITY_HSTS_PRELOAD_ENABLED |
false |
When true, adds the preload directive. Preload submission is one-way — opt in deliberately. |
APP_SERVER_SECURITY_CONTENT_SECURITY_POLICY |
— | Content-Security-Policy header value (sent verbatim when non-empty). Empty by default to avoid breaking the bundled Swagger UI. |
APP_SERVER_SECURITY_REFERRER_POLICY |
— | Referrer-Policy header value (sent verbatim when non-empty). Common values: no-referrer, strict-origin-when-cross-origin. |
APP_SERVER_CSRF_ENABLED |
false |
Enable Echo's CSRF middleware. Off by default — opt in once the application uses session cookies. |
APP_SERVER_CSRF_TOKEN_LOOKUP |
header:X-CSRF-Token |
Echo <source>:<name> syntax. Comma-separated alternatives allowed (e.g. header:X-CSRF-Token,form:csrf). |
APP_SERVER_CSRF_COOKIE_NAME |
_csrf |
Cookie that stores the CSRF token. |
APP_SERVER_CSRF_COOKIE_DOMAIN |
— | Cookie Domain attribute. Empty leaves it as the request host. |
APP_SERVER_CSRF_COOKIE_PATH |
— | Cookie Path attribute. Empty leaves it at /. |
APP_SERVER_CSRF_COOKIE_MAX_AGE |
86400 |
Cookie lifetime in seconds. 0 issues a session cookie. |
APP_SERVER_CSRF_COOKIE_SECURE |
false |
Restrict the cookie to HTTPS responses. Production behind TLS should set true. |
APP_SERVER_CSRF_COOKIE_HTTP_ONLY |
true |
Hide the cookie from JavaScript. Defeats most XSS-driven token theft. |
APP_SERVER_CSRF_COOKIE_SAME_SITE |
— | One of default, lax, strict, none (case-insensitive). Empty inherits Echo's SameSiteDefaultMode. |
APP_SERVER_RATE_LIMIT_ENABLED |
false |
Per-client request-rate limiter keyed off RealIP(). Returns 429 when exceeded. Off by default. |
APP_SERVER_RATE_LIMIT_RATE |
0 |
Steady-state allowed requests per second per client IP. Required when ENABLED=true. |
APP_SERVER_RATE_LIMIT_BURST |
0 |
Bucket size — clients may make this many requests in one shot before the rate kicks in. Zero falls back to ceil(rate). |
APP_SERVER_RATE_LIMIT_EXPIRES_IN |
3m |
Inactivity TTL for a per-client bucket before the memory store evicts it. |
APP_SERVER_RATE_LIMIT_MAX_CONNECTIONS |
0 |
Cap on simultaneous TCP connections per listener (HTTP and HTTPS each independently). Zero disables the cap. |
APP_DATABASE_DRIVER |
pgx |
database/sql driver name (PostgreSQL via pgx) |
APP_DATABASE_DSN |
— | Connection string. Empty disables the database subsystem entirely (Connect/Migrate become no-ops, readiness probe ignores DB state). |
APP_DATABASE_MAX_OPEN_CONNS |
25 |
Max open connections in the pool. Zero/negative = unlimited. |
APP_DATABASE_MAX_IDLE_CONNS |
5 |
Max idle connections retained in the pool |
APP_DATABASE_CONN_MAX_LIFETIME |
1h |
Max lifetime of a connection before recycling |
APP_DATABASE_CONN_MAX_IDLE_TIME |
5m |
Max time a connection may sit idle in the pool |
APP_OPENAPI_ENABLED |
true |
Serve generated /openapi.yaml and /openapi.json |
APP_OPENAPI_TITLE |
appsvrd |
OpenAPI info.title (defaults to daemon name) |
APP_OPENAPI_VERSION |
embedded SemVer | OpenAPI info.version (defaults to internal/version.Number()) |
APP_OPENAPI_DESCRIPTION |
— | OpenAPI info.description |
APP_OPENAPI_SWAGGER_ENABLED |
false |
Mount Swagger UI |
APP_OPENAPI_SWAGGER_PATH |
/swagger |
URL prefix Swagger UI is mounted under |
APP_OPENAPI_SWAGGER_SPEC_URL |
/openapi.yaml |
URL Swagger UI fetches the spec from |
See internal/application/config_*.go for the complete schema.
The default v1 module ships three Kubernetes-style health endpoints under /api/v1/. Response bodies follow the per-component model used by Spring Boot Actuator, Quarkus SmallRye Health, and Micronaut: an overall status plus a components map with per-subsystem state and optional details.
| Path | Purpose | Status code | Components |
|---|---|---|---|
/api/v1/livez |
Liveness probe | Always 200. Liveness must NOT depend on application state — kubelet uses it to decide whether to restart the pod. |
self only. |
/api/v1/readyz |
Readiness probe | 200 when every registered component reports UP; 503 when any component reports DOWN (or when no registry is wired — fail closed). |
All active subsystems: lifecycle, http, https (if enabled), database (if configured). |
/api/v1/healthz |
Legacy alias for readyz | Same as /readyz. |
Same as /readyz. Kept so consumers that default to /healthz (older uptime checks, default cloud-LB health-check paths) keep working. |
Example /readyz response when everything is healthy and a database is configured:
{
"status": "UP",
"components": {
"lifecycle": { "status": "UP" },
"http": { "status": "UP", "details": { "port": 8080, "bindAddress": "", "hostname": "" } },
"https": { "status": "UP", "details": { "port": 8443, "bindAddress": "", "hostname": "", "autoCertIssuance": true, "useAcmeIssuer": false, "ephemeralCertIssuance": true } },
"database": { "status": "UP", "details": { "driver": "pgx" } }
}
}When the database is unreachable, the response code becomes 503 and the body's overall status flips to DOWN while the per-component breakdown shows which dependency failed.
Both response formats are supported via the Accept header:
Accept header |
Response Content-Type |
|---|---|
(unset), */*, application/json, anything not yaml |
application/json; charset=utf-8 |
application/yaml, application/x-yaml, text/yaml, *+yaml |
application/yaml; charset=utf-8 |
curl -s http://localhost:8080/api/v1/readyz # JSON
curl -s -H 'Accept: application/yaml' http://localhost:8080/api/v1/readyz # YAMLComponents live on a *health.Registry owned by the Application (app.HealthRegistry()); the v1 handlers snapshot it on every request. To register a new check:
app.HealthRegistry().Register("redis", func() health.ComponentResult {
if err := redisClient.Ping(ctx).Err(); err != nil {
return health.ComponentResult{
Status: health.StatusDown,
Details: map[string]any{"reason": err.Error()},
}
}
return health.ComponentResult{Status: health.StatusUp}
})The check closure is invoked on every /readyz and /healthz request, so it should be cheap (sub-second). Stand a cached background probe in front of expensive checks.
The starter generates an OpenAPI 3.0.3 document directly from whatever modules are registered with Application and serves it without any external tooling. No annotations, no swag init, no codegen step — the spec is built in-process during Initialize() and served as precomputed bytes.
| Path | Format | Notes |
|---|---|---|
/openapi.yaml |
YAML | application/yaml; charset=utf-8 |
/openapi.json |
JSON | application/json; charset=utf-8 |
Both endpoints are mounted unconditionally when APP_OPENAPI_ENABLED=true (the default). Set APP_OPENAPI_ENABLED=false to suppress them entirely (e.g. for production deployments that don't want to advertise their API surface).
The generator walks the Module → Route → Endpoint tree and emits one operation per (path, method) pair. Echo's :name path parameters are rewritten to OpenAPI's {name} template syntax, and a Parameter of in: path, type: string is emitted for each. Each module's Name() becomes a tag so Swagger UI groups operations by module.
Endpoints opt into richer documentation via builder options on endpoint. The reflection-based schema generator at internal/openapi/schema.go converts the Go types you declare into JSON Schemas, registers each named struct under components.schemas, and operations reference it via $ref so each shape appears once in the spec.
endpoint.New("user-create-post", "user-create-post",
endpoint.WithPostMethod(),
endpoint.WithSummary("Create a user"),
endpoint.WithDescription("Persists a new user record."),
endpoint.WithRequest(CreateUserRequest{}), // application/json body
endpoint.WithResponse(http.StatusCreated, User{}, "Created"), // 201 with User schema
endpoint.WithResponse(http.StatusBadRequest, ErrorResponse{}, "Validation failed"),
endpoint.WithHandler(createUser),
)What the generator handles:
| Go construct | OpenAPI representation |
|---|---|
string, bool, ints, floats |
inline scalar with type + format set |
time.Time |
type: string, format: date-time |
[]byte |
type: string, format: byte (base64) |
| Other slices | type: array, items: <inner> |
map[string]T |
type: object, additionalProperties: <T> |
*T |
schema for T with nullable: true (or omitted from required) |
| Named struct | registered under components.schemas, referenced via $ref |
| Anonymous struct | inlined |
| Embedded struct | fields lifted into the parent schema (matches encoding/json) |
any / interface{} |
free-form schema (no type constraint) |
Recursive struct (A → *A) |
$ref back to the same schema (no infinite recursion) |
JSON struct tags are honored: json:"name" renames the property, omitempty excludes the field from required, and json:"-" skips it entirely. Unexported fields are skipped, but embedded struct fields are lifted regardless of the embedded field's name visibility (matches encoding/json flattening).
Endpoints without any WithResponse calls fall back to a generic 200: Successful response so the spec stays valid; once you declare any response, the generator uses your declarations exclusively (no auto-200 is appended).
Set APP_OPENAPI_SWAGGER_ENABLED=true to mount Swaggo's echo-swagger v2 at /swagger/, pointed at the generated spec by default:
APP_OPENAPI_SWAGGER_ENABLED=true task run:daemon
# then open: http://localhost:8080/swagger/index.htmlThe dependency is always compiled in (~1MB binary overhead) but no routes are mounted unless Swagger.Enabled is true. Override APP_OPENAPI_SWAGGER_PATH to mount under a different prefix, or APP_OPENAPI_SWAGGER_SPEC_URL to point the UI at an externally hosted spec.
The starter ships an opt-in database layer using:
pgxas thedatabase/sqldriver (PostgreSQL).pressly/goosefor SQL schema migrations, embedded into the binary via//go:embed internal/database/migrations/sql/*.sql.uptrace/bunas the ORM, configured against the same*sql.DBconnection pool.
To enable: set APP_DATABASE_DSN (e.g. postgres://user:pass@host:5432/db?sslmode=disable). On startup the daemon will:
database.Connect(cfg)— open the pool and verify reachability with a ping.database.Migrate(cfg)— apply pending Goose migrations frominternal/database/migrations/sql/.orm.Configure()— wrap the connection in a Bun*bun.DBsingleton accessible viaorm.Database().
To add a migration, drop a new YYYYMMDDHHMMSS_description.sql file alongside the no-op initial migration and rebuild — the embed pattern picks it up automatically. The default Driver is pgx; replace the driver, the dialect in internal/database/orm/connection.go, and the goose.SetDialect argument in migration.go to swap engines.
Routes are attached to modules. The v1 API module already wires the three health routes above; new endpoints go under internal/api/v1/ and are added to the module via WithRoutes(...).
The relevant constructors are:
module.New(id, name, prefix string, opts ...module.Option)— options:WithRoutes,WithSubModules,WithMiddlewareroute.New(id, name, path string, opts ...route.Option)— options:WithEndpoints,WithMiddlewareendpoint.New(id, name string, opts ...endpoint.Option)— options:WithHandler,WithMethods(or convenienceWithGetMethod,WithPostMethod, etc.),WithMiddleware
Echo v5 handlers receive *echo.Context (pointer), not the v4 interface.
A typical pattern:
// internal/api/v1/ping.go
package v1
import (
"net/http"
"github.com/labstack/echo/v5"
"github.com/servercurio/go-echo-starter/internal/api/std/endpoint"
"github.com/servercurio/go-echo-starter/internal/api/std/route"
"github.com/servercurio/go-echo-starter/internal/router"
)
func PingRoute() router.Route {
return route.New("ping", "ping", "/ping",
route.WithEndpoints(
endpoint.New("ping-get", "ping-get",
endpoint.WithGetMethod(),
endpoint.WithHandler(func(c *echo.Context) error {
return c.JSON(http.StatusOK, map[string]string{"pong": "ok"})
}),
),
),
)
}Then wire it into internal/api/v1/module.go by adding PingRoute() to the existing module.WithRoutes(...) call. Routes that need application state (e.g. readiness, config) take a *router.Config argument like ReadinessRoute(cfg) does.
| Task | Description |
|---|---|
task / task default |
Clean → vendor → lint → build all platform binaries |
task build |
Cross-compile for all OS/arch combinations (calls generate) |
task generate |
go generate ./... — refresh internal/version/commit.txt |
task hash |
Write a bin/<binary>.sha256 file per binary |
task sign |
GPG-sign each .sha256 file (writes <binary>.sha256.asc); depends on hash. Binaries themselves are NOT signed — the signed hash transitively pins the binary. |
task sbom |
Generate the Go module CycloneDX SBOM (bin/sbom.json + bin/sbom.xml) and GPG-sign each output |
task vendor |
go mod tidy + go mod vendor |
task lint |
go fmt + go vet with strict checks |
task test |
go test -race -cover -coverprofile cover.out -parallel 4 -v ./... |
task run:daemon |
Build and run the local-platform binary |
task build:container |
Build the Docker image locally (single-arch, --load into the daemon) |
task run:container |
Build and run the Docker image |
task container:build:multiarch |
Multi-arch (linux/amd64,linux/arm64) buildx push to ghcr.io/servercurio/go-echo-starter. Reads version from internal/version/version.txt. Used by the release pipeline. |
task container:sbom |
Generate the container image CycloneDX SBOM (bin/container-sbom.{json,xml}) via syft |
task container:sbom:sign |
GPG-sign the container SBOM files |
task helm:lint |
helm lint charts/go-echo-starter |
task helm:template |
Render the chart with the full-values fixture, monitoring CRDs, and TLS overlay (catches gated-resource regressions) |
task helm:package |
Package the chart into bin/go-echo-starter-<VERSION>.tgz |
task helm:hash |
SHA-256 hash the packaged chart |
task helm:sign |
GPG-sign the chart hash file (<chart>.tgz.sha256.asc); the .tgz itself is NOT signed |
task helm:sbom |
Generate the helm chart CycloneDX SBOM (bin/helm-sbom.{json,xml}) via syft |
task helm:sbom:sign |
GPG-sign the helm SBOM files |
task helm:test |
Run chart-testing (ct lint) against charts/ |
task helm:push:oci |
Push the packaged chart to oci://ghcr.io/servercurio/charts |
task clean |
Remove bin/, dist/, and coverage output |
The default identifiers (appsvrd, APP_* env-var prefix, appsvr config-path element) are intentional defaults you'll want to replace per project. There are five places to touch — keep them consistent or you'll get half-renamed binaries that look in the wrong config paths.
In the examples below, assume you're renaming to myapi with binary myapid, env-var prefix MYAPI, and config-path element myapi.
vars:
PROJECT_NAME: MyApi # was: AppSvr → produces "myapid" binary (lowercase + 'd' suffix)PROJECT_NAME is templated as {{.PROJECT_NAME | lower}}d to produce the binary name (bin/myapid-${GOOS}-${GOARCH}) and the Docker image tag (myapi:latest). It must align with the Go-side defaultName constant — the binary won't be able to identify itself in logs otherwise.
env:
CGO_ENABLED: 0
MYAPI_DAEMON_LOG_LEVEL: trace
MYAPI_DAEMON_LOG_INCLUDE_CALLER: false
MYAPI_HTTP_ACCESS_LOG_ENABLED: true
MYAPI_HTTP_ACCESS_LOG_LEVEL: info
MYAPI_HTTP_ACCESS_LOG_PRETTY_PRINT: true
MYAPI_SERVER_HTTPS_ENABLED: true
MYAPI_SERVER_HTTP_PORT: 80
MYAPI_SERVER_HTTPS_PORT: 443
MYAPI_SERVER_HTTPS_USE_ACME_ISSUER: falseThese developer-convenience overrides only take effect when task runs — but they must use the new prefix or they'll be silently ignored after step 3.
const defaultName = "myapid" // binary identity in logs
const defaultEnvPrefix = "MYAPI" // env-var prefix (no trailing underscore)
const defaultConfigName = "myapid" // base filename for config files (myapid.yaml, myapid.json)
const defaultConfigPathElement = "myapi" // directory segment in /etc/<x>/, ~/.config/<x>/defaultEnvPrefix is the source of truth — it's what env.AddPrefix uses to build keys like MYAPI_DAEMON_LOG_LEVEL. The Taskfile env values from step 2 must use this exact prefix (no underscore at the end of the constant; the joiner adds it).
defaultConfigPathElement controls the config-file search paths in internal/application/utils.go:
/etc/myapi/~/.config/myapi/./(current directory)
defaultConfigName controls the filename — files are looked up as myapid.yaml, myapid.yml, or myapid.json in each search path.
# Pinned to ubuntu:noble-20260410 by digest for supply-chain integrity.
# Multi-arch manifest list covers linux/amd64 and linux/arm64 (the build
# matrix's two targets). Dependabot's docker ecosystem opens PRs that bump
# both the tag and the digest together.
FROM ubuntu:noble-20260410@sha256:c4a8d5503dfb2a3eb8ab5f807da5bc69a85730fb49b5cfca2330194ebcc41c7b
COPY ./bin/ /tmp/myapi/
RUN mkdir -p /tmp/myapi && \
ls -lah /tmp/myapi && \
ARCH="$(dpkg --print-architecture)" && \
case "$ARCH" in \
x86_64|amd64) ARCH="amd64" ;; \
aarch64|arm64) ARCH="arm64" ;; \
*) echo "Unsupported architecture: $ARCH" && exit 1 ;; \
esac && \
cp -v /tmp/myapi/myapid-linux-${ARCH} /usr/local/bin/myapid && \
chmod 0755 /usr/local/bin/myapid && \
chown root:root /usr/local/bin/myapid && \
rm -rf /tmp/myapi && \
groupadd --system --gid 10001 myapi && \
useradd --system --uid 10001 --gid 10001 --shell /usr/sbin/nologin \
--no-create-home --comment "myapid service account" myapi
USER 10001:10001
CMD ["myapid"]Replace appsvr (path element) and appsvrd (binary name) on every line. The binary name in the cp source must match what task build:daemon produces (i.e. derived from PROJECT_NAME).
When you re-pin the base image for your fork, run docker pull ubuntu:noble-<date> and copy the resulting Digest: line into the FROM clause. Once the workflow is checked in, Dependabot's docker ecosystem will keep the tag-plus-digest pair updated for you.
const envPrefix = "MYAPI"This test sets env vars under a custom prefix to exercise the env.AddPrefix path. Update it to match your new defaultEnvPrefix so the test continues to actually exercise the configured prefix.
If you're shipping the chart yourself, rename charts/go-echo-starter/ to charts/myapi/ and update:
Chart.yaml—name: myapi,description,sources,hometemplates/_helpers.tpl— everygo-echo-starter.<helper>definition (the chart-name prefix onname,fullname,chart,labels,selectorLabels,serviceAccountName,image,secretName,configmapName,validateSeccompProfile)- Every template file's
{{ include "go-echo-starter.<helper>" . }}calls image.repositoryinvalues.yaml(point at your registry/image path)Taskfile.yaml— thehelm:lint/helm:template/helm:package/helm:sbom/helm:push:ocichart paths and OCI registry path.releaserc.json— chart.tgzasset paths under@semantic-release/github.github/workflows/800-call-semantic-release.yaml—subject-namefields under the helm OCI attestation steps
If you're forking under a new owner, also update the module path in go.mod:
module github.com/your-org/your-repo
Then run task vendor to refresh imports across the codebase. Imports that reference github.com/servercurio/go-echo-starter/internal/... will need a find-and-replace.
task # full pipeline rebuilds everything
task run:daemon # confirm the renamed binary boots and logs use the new nameThe startup log should show your new binary name and config search paths matching your new defaultConfigPathElement.
task build:container # local single-arch build, --load into the Docker daemon
task run:container # build and run locallyThe image is built from a date-pinned ubuntu:noble-* tag (see Dockerfile) and ships a single static binary built with CGO_ENABLED=0. The bundled HEALTHCHECK curls /api/v1/livez every 30s.
The release pipeline publishes a multi-arch (linux/amd64, linux/arm64) image to GHCR via task container:build:multiarch; the published manifest digest is captured into bin/container-image.digest and used by the workflow's attestation steps. Pull the published image with:
docker pull ghcr.io/servercurio/go-echo-starter:<version>
# or by digest, after gh attestation verify:
docker pull ghcr.io/servercurio/go-echo-starter@<digest>A production-ready Helm chart lives at charts/go-echo-starter/. It targets Kubernetes 1.27+ and ships with the standard scaffolding (Deployment, Service, ServiceAccount, Ingress, HPA, ConfigMap) plus opt-in observability and policy resources.
From the GHCR OCI registry (recommended):
helm install my-app oci://ghcr.io/servercurio/charts/go-echo-starter --version <X.Y.Z>Or from a release .tgz asset:
gh release download v<X.Y.Z> --repo servercurio/go-echo-starter --pattern 'go-echo-starter-*.tgz'
helm install my-app ./go-echo-starter-<X.Y.Z>.tgz- Defaults that match the daemon: probes against
/api/v1/livezand/api/v1/readyz, ports 8080 (HTTP) and 8443 (HTTPS), non-root UID 10001, read-only root filesystem, dropped capabilities,RuntimeDefaultseccomp at both pod and container scope,emptyDirmounted at/tmp. - Seccomp validation:
podSecurityContext.seccompProfileandsecurityContext.seccompProfileacceptRuntimeDefault/Localhost/Unconfined. A helper template fails the install at render time whentypeis invalid or whenLocalhostis used withoutlocalhostProfile. - User-supplied secrets: reference any pre-existing
SecretorConfigMapvia.Values.envFrom; mount additional volumes via.Values.extraVolumes/.Values.extraVolumeMounts. - TLS via existing Secret: set
tls.enabled=trueandtls.existingSecret=<secret-name>(Secret must containtls.crtandtls.key). The chart mounts it attls.mountPathand points the daemon at it viaAPP_SERVER_HTTPS_*. - Optional, capability-guarded resources (all default
enabled: falseso the chart installs cleanly on clusters without the CRDs):metrics.serviceMonitor—monitoring.coreos.com/v1 ServiceMonitor(Prometheus Operator)metrics.podMonitor—monitoring.coreos.com/v1 PodMonitor(Prometheus Operator)logging.podLogs—monitoring.grafana.com/v1alpha2 PodLogs(Grafana Alloy)podDisruptionBudget,networkPolicy,autoscaling,ingress, Gateway-APIhttpRoute
Every release ships GitHub-signed Sigstore attestations for both the OCI artifact and the .tgz:
gh attestation verify oci://ghcr.io/servercurio/charts/go-echo-starter:<X.Y.Z> --owner servercurio
gh attestation verify ./go-echo-starter-<X.Y.Z>.tgz --owner servercurioThe chart .tgz's SHA256 is also GPG-signed:
gpg --verify go-echo-starter-<X.Y.Z>.tgz.sha256.asc go-echo-starter-<X.Y.Z>.tgz.sha256
shasum -a 256 -c go-echo-starter-<X.Y.Z>.tgz.sha256See charts/go-echo-starter/README.md for the full values reference and per-resource configuration details.
Releases are produced by semantic-release and triggered manually via the Deploy Release workflow (100-user-deploy-release-artifact.yaml) under the GitHub Actions tab. The release flow:
- Analyses commits since the last tag using the conventional-commits preset and decides the next semver version.
- Updates
internal/version/version.txtto the new version and runstask generateto refreshcommit.txt. - Commits the version bump back to the release branch with a
chore(release): X.Y.Z [skip ci]message. The commit is GPG-signed (DCOSigned-off-byis appended automatically by a per-cloneprepare-commit-msghook installed in CI). - Runs
task build(six platform binaries) →task hash+task sign(per-binary SHA256 files and GPG signatures of the hashes) →task sbom(Go module CycloneDX SBOM, JSON + XML, GPG-signed) →task container:build:multiarch(multi-arch buildx push toghcr.io/servercurio/go-echo-starter) →task container:sbom+task container:sbom:sign(container CycloneDX SBOM, JSON + XML, GPG-signed) →task helm:package+task helm:hash+task helm:sign(chart.tgz, hash, signed hash) →task helm:sbom+task helm:sbom:sign(helm CycloneDX SBOM, JSON + XML, GPG-signed) →task helm:push:oci(push chart tooci://ghcr.io/servercurio/charts). - Tags the commit and creates a GitHub Release. Every file artifact is uploaded as a release asset; container image and helm OCI artifact live in GHCR.
- Issues GitHub-signed Sigstore attestations via
actions/attest-build-provenance(covering every release file plus both OCI subjects) andactions/attest-sbom(binding each CycloneDX SBOM, JSON and XML, to its subjects). OCI attestations are pushed alongside the manifest in GHCR.
| Artifact class | Files / subjects | Notes |
|---|---|---|
| Binaries | appsvrd-{linux,darwin,windows}-{amd64,arm64} (6 total) |
No per-binary GPG signature — verify via the signed hash file |
| Hash files | <binary>.sha256 + <binary>.sha256.asc |
.asc is the detached GPG signature of the hash file |
| Container image | ghcr.io/servercurio/go-echo-starter:<version> and :latest |
Multi-arch manifest list (linux/amd64 + linux/arm64); attestations pushed to GHCR |
| Helm chart (file) | go-echo-starter-<version>.tgz + .tgz.sha256 + .tgz.sha256.asc |
Available as a GitHub release asset |
| Helm chart (OCI) | oci://ghcr.io/servercurio/charts/go-echo-starter:<version> |
helm install directly from the registry |
| Go SBOM | sbom.json + sbom.xml + .asc companions |
CycloneDX, generated by cyclonedx-gomod |
| Container SBOM | container-sbom.json + container-sbom.xml + .asc companions |
CycloneDX, generated by syft against the published image |
| Helm chart SBOM | helm-sbom.json + helm-sbom.xml + .asc companions |
CycloneDX, generated by syft against the packaged .tgz |
| Attestations | One attest-build-provenance per release file + one per OCI subject; one attest-sbom per (SBOM format, subject) pair |
Stored in the GitHub attestation log and (for OCI subjects) alongside the manifest in GHCR |
The recommended path is gh attestation verify, which works for both file artifacts and OCI subjects without any pre-shared key:
# Binary
gh attestation verify appsvrd-linux-amd64 --owner servercurio
# Hash file (proves universal coverage of every released file)
gh attestation verify appsvrd-linux-amd64.sha256 --owner servercurio
# Go SBOM
gh attestation verify sbom.json --owner servercurio
# Helm chart (file)
gh attestation verify go-echo-starter-<X.Y.Z>.tgz --owner servercurio
# Container image (provenance + container SBOM, fetched from GHCR)
gh attestation verify oci://ghcr.io/servercurio/go-echo-starter:<X.Y.Z> --owner servercurio
# Helm OCI artifact (provenance + helm SBOM, fetched from GHCR)
gh attestation verify oci://ghcr.io/servercurio/charts/go-echo-starter:<X.Y.Z> --owner servercurioFor offline-capable verification, use the GPG-signed hash files. Note that binaries themselves are no longer GPG-signed — only the .sha256 files are. The signed hash transitively pins the binary, so:
# byte-correctness only
shasum -a 256 -c appsvrd-linux-amd64.sha256
# verify the hash file was signed by the release key, then check the binary against it
gpg --verify appsvrd-linux-amd64.sha256.asc appsvrd-linux-amd64.sha256
shasum -a 256 -c appsvrd-linux-amd64.sha256CycloneDX SBOM files (sbom.json, container-sbom.json, helm-sbom.json and their .xml variants) are signed directly because the SBOM file is itself the manifest:
gpg --verify sbom.json.asc sbom.jsonBranch policy (from .releaserc.json):
| Branch pattern | Channel | Notes |
|---|---|---|
main |
latest | Default release branch |
release/X.Y |
X.Y.x |
Maintenance branches; release range pinned to X.Y.x |
alpha/* |
alpha |
Prerelease channel |
beta/* |
beta |
Prerelease channel |
rc/* |
rc |
Release-candidate channel |
Release rules (commit type → version bump):
| Type | Bump |
|---|---|
feat |
minor |
fix |
patch |
refactor, build |
patch |
BREAKING CHANGE (footer or ! in subject) |
minor |
chore, ci, docs, style, test |
none |
Run a dry run from the workflow dispatch UI by checking Perform dry run — semantic-release will print the version that would be released without tagging, committing, or publishing.
Note on protected branches: the workflow uses the default
GITHUB_TOKEN. Ifmainis protected with restrictions that block the GitHub App from pushing back the version-bump commit, configure a PAT (e.g.GH_ACCESS_TOKEN) with bypass rights and pass it asrelease-tokenfrom100-user-deploy-release-artifact.yaml.
The release workflow requires the following secrets configured under Settings → Secrets and variables → Actions:
| Secret | Purpose |
|---|---|
GPG_PRIVATE_KEY |
ASCII-armored private GPG key used to sign the release commit and every .sha256 / SBOM file. Generate with gpg --armor --export-secret-keys <KEY-ID>. |
GPG_PASSPHRASE |
Passphrase for the private GPG key. |
GH_ACCESS_TOKEN |
(Optional.) PAT used as release-token when GITHUB_TOKEN can't satisfy a constraint. The token must carry: contents: write (release commits and tags), packages: write (GHCR push for the container image and helm OCI chart), id-token: write (OIDC for Sigstore Fulcio), and attestations: write. The default GITHUB_TOKEN already has these scopes when the workflow declares the matching permissions: block; a PAT is only needed when branch protection blocks the App-bound default token. |
CODECOV_TOKEN |
(Optional, used by PR Checks.) Codecov upload token; recommended for public repos to avoid rate limits, required for private repos. |
The corresponding public key must be added to the GitHub account/org used to publish releases (and shared with consumers) so signatures can be verified.
See LICENSE.