Add Initial Quickstart/Starter Kit ⚙️

.github/workflows/docker.yaml

@@ -0,0 +1,118 @@
+# This workflow builds and pushes a multi-arch image to GHCR
+# Adapted from actions-arm64-native-example by @gartnera
+# ref: https://github.com/gartnera/actions-arm64-native-example/blob/main/.github/workflows/build.yml
+
+name: build
+
+on:
+  push:
+
+permissions:
+  contents: read
+  packages: write
+
+env:
+  GHCR_REPO: ghcr.io/${{ github.repository_owner }}/${{ github.event.repository.name }}
+
+jobs:
+  build:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: linux/amd64
+            runner: ubuntu-24.04
+          - platform: linux/arm64
+            runner: ubuntu-24.04-arm
+    runs-on: ${{ matrix.runner }}
+    steps:
+      - name: Prepare
+        run: |
+          platform=${{ matrix.platform }}
+          echo "PLATFORM_PAIR=${platform//\//-}" >> $GITHUB_ENV
+
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+             ${{ env.GHCR_REPO }}
+
+      - name: Login to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Build and push by digest
+        id: build
+        uses: docker/build-push-action@v6
+        with:
+          platforms: ${{ matrix.platform }}
+          labels: ${{ steps.meta.outputs.labels }}
+          outputs: type=image,name=${{ env.GHCR_REPO }},push-by-digest=true,name-canonical=true,push=true
+
+      - name: Export digest
+        run: |
+          mkdir -p ${{ runner.temp }}/digests
+          digest="${{ steps.build.outputs.digest }}"
+          touch "${{ runner.temp }}/digests/${digest#sha256:}"          
+
+      - name: Upload digest
+        uses: actions/upload-artifact@v4
+        with:
+          name: digests-${{ env.PLATFORM_PAIR }}
+          path: ${{ runner.temp }}/digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+  merge:
+    runs-on: ubuntu-latest
+    needs:
+      - build
+    steps:
+      - name: Download digests
+        uses: actions/download-artifact@v4
+        with:
+          path: ${{ runner.temp }}/digests
+          pattern: digests-*
+          merge-multiple: true
+
+      - name: Login to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Docker meta
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: |
+            ${{ env.GHCR_REPO }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=ref,event=tag
+            type=sha,prefix=
+
+      - name: Create manifest list and push
+        working-directory: ${{ runner.temp }}/digests
+        run: |
+          docker buildx imagetools create $(jq -cr '.tags | map("-t " + .) | join(" ")' <<< "$DOCKER_METADATA_OUTPUT_JSON") \
+            $(printf '${{ env.GHCR_REPO }}@sha256:%s ' *)          
+
+      - name: Inspect image
+        run: |
+          docker buildx imagetools inspect ${{ env.GHCR_REPO }}:${{ steps.meta.outputs.version }}

Dockerfile

@@ -0,0 +1,54 @@
+# Multi-stage build for Go application
+FROM golang:1.24-alpine AS builder
+
+# Set the working directory
+WORKDIR /app
+
+# Install git for submodule operations
+RUN apk add --no-cache git
+
+# Copy go mod files
+COPY go.mod go.sum ./
+
+# Download dependencies
+RUN go mod download
+
+# Copy source code
+COPY . .
+
+# Build the application
+RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o drs-server ./cmd/server
+
+# Final lightweight image
+FROM alpine:latest
+
+# Install ca-certificates for HTTPS requests
+RUN apk --no-cache add ca-certificates
+
+# Create non-root user
+RUN addgroup -g 1001 -S appgroup && \
+    adduser -u 1001 -S appuser -G appgroup
+
+WORKDIR /app
+
+# Copy the binary from builder stage
+COPY --from=builder /app/drs-server .
+
+# Copy the OpenAPI spec file
+COPY --from=builder /app/internal/apigen/api/openapi.yaml ./internal/apigen/api/openapi.yaml
+
+# Change ownership to non-root user
+RUN chown -R appuser:appgroup /app
+
+# Switch to non-root user
+USER appuser
+
+# Expose port 8080
+EXPOSE 8080
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
+    CMD wget --no-verbose --tries=1 --spider http://localhost:8080/healthz || exit 1
+
+# Run the application
+CMD ["./drs-server"]

Makefile

@@ -40,8 +40,11 @@ docs-image:
 
 # Serve the MkDocs documentation locally with live reload
 .PHONY: docs
-docs:
-	docker run --rm -it \
+docs: docs-serve
+
+.PHONY: docs-serve
+docs-serve:
+	docker run --rm \
 	  -v "$(PWD):/docs" \
 	  -p 8000:8000 \
 	  $(MKDOCS_IMAGE) \
@@ -55,3 +58,4 @@ docs-build:
 	  -p 8000:8000 \
 	  $(MKDOCS_IMAGE) \
 	  build
+

docs/index.md

@@ -18,3 +18,30 @@ graph LR
     B --> C[Data Storage]
     B --> D[Metadata DB]
 ```
+
+## Quick Start ⚡️
+
+!!! warning
+    Add steps that actually interact with the **DRS Server**:
+
+    - [ ] Listing
+    - [ ] Registering
+    - [ ] Retrieving/Resolving DRS URI's → files
+
+```sh
+# TODO: Change to latest tag when stable
+# docker run -p 8080:8080 ghcr.io/calypr/drs-server:latest
+
+➜ docker run -p 8080:8080 ghcr.io/calypr/drs-server:feature-actions
+{
+  "level": "info",
+  "caller": "server/main.go:123",
+  "msg": "listening",
+  "addr": ":8080"
+}
+
+➜ curl localhost:8080/healthz
+{
+  "status": "ok"
+}
+```

mkdocs.yml

@@ -27,6 +27,9 @@ markdown_extensions:
   - admonition
   - toc:
       permalink: true
+  - pymdownx.details
+  - pymdownx.tasklist:
+      custom_checkbox: true
   - pymdownx.superfences:
       custom_fences:
         - name: mermaid

requirements.txt

@@ -0,0 +1,6 @@
+# Dependencies required for build preview on Netlify
+mkdocs
+mkdocs-material
+mkdocs-mermaid2-plugin
+pymdown-extensions
+