Scaffold Cloudron packaging workspace

.gitea/workflows/ci.yml

@@ -2,25 +2,19 @@ name: cloudron-packages-ci
 
 on:
   workflow_dispatch:
-    inputs:
-      tasks:
-        description: "Space-separated list of tasks to run via scripts/ci_local.sh"
-        required: false
-        default: "all"
 
 jobs:
-  lint-and-smoke:
+  lint-and-status:
     runs-on: ubuntu-22.04
     steps:
       - name: Checkout repository
         uses: https://gitea.com/actions/checkout@v4
 
-      - name: Build CI harness image
+      - name: Build devtools image if needed
-        run: docker build -t knel/cloudron-ci docker/ci-runner
+        run: ./run/dev.sh python --version
 
-      - name: Run requested tasks
+      - name: Lint repository (strict mode)
-        env:
+        run: ./run/dev.sh python scripts/lint_repo.py --strict
-          TASKS: ${{ github.event.inputs.tasks }}
+
-        run: |
+      - name: Regenerate status dashboard
-          export CI_IMAGE=knel/cloudron-ci
+        run: ./run/dev.sh python scripts/generate_status.py --preserve-timestamp
-          ./scripts/ci_local.sh ${TASKS:-all}

.gitignore

@@ -2,3 +2,4 @@ __pycache__/
 *.pyc
 *.swp
 .DS_Store
+.venv/

AGENTS.md

@@ -0,0 +1,37 @@
+# Agent Operations Guide
+
+## Non-negotiable rules
+
+- Host commands are limited to `git`, `docker`, and `curl`. Everything else runs inside the provided wrapper scripts.
+- Use `./run/dev.sh` for all development automation (scaffolding, linting, status updates).
+- Use `./run/packager.sh` for packaging tasks that require the Cloudron CLI.
+- Containers mount the repo at `/workspace`; do not write outside it.
+
+## Images
+
+- `knel/cloudron-devtools` – built automatically by `./run/dev.sh`; contains Python tooling.
+- `knel/cloudron-packager` – built automatically by `./run/packager.sh`; contains the Cloudron CLI.
+
+## Common workflows
+
+```bash
+# Generate/refresh a scaffold
+./run/dev.sh python scripts/new_app.py --slug apache-apisix
+
+# Regenerate the full catalog (overwrites existing scaffolds)
+./run/dev.sh python scripts/new_app.py --force
+
+# Lint an app (fails on TODO placeholders)
+./run/dev.sh python scripts/lint_repo.py --slug apache-apisix --strict
+
+# Refresh docs/APP_STATUS.md without changing the timestamp
+./run/dev.sh python scripts/generate_status.py --preserve-timestamp
+
+# Open the Cloudron packaging shell (add BUILD=1 to rebuild the image first)
+./run/packager.sh
+```
+
+## Notes
+
+- The first invocation of either wrapper builds the corresponding Docker image if it is missing.
+- Update documentation whenever command sequences change so future agents stay aligned.

GEMINI/AUDIT-SNAPSHOT2.md

@@ -0,0 +1,51 @@
+# Gemini Audit Report: KNELCloudronPackages (Final Verification)
+
+**Date:** 2025-10-02
+**Auditor:** Gemini
+**Scope:** Final verification of repository state after mandatory cleanup.
+
+---
+
+## 1. Executive Summary
+
+This audit confirms that the mandatory cleanup instructions outlined in the previous report (`GEMINI/FIX-1.md`) have been executed successfully and precisely. The repository's foundational workflow, which was previously broken and contradictory, is now **clean, consistent, and robust.**
+
+All non-compliant orchestration files have been removed and replaced with a set of simple, effective wrapper scripts in the `run/` directory. The documentation has been updated to reflect this single, unified workflow. Critical technical debt, most notably the missing `memoryLimit` placeholder, has been resolved.
+
+The project is no longer blocked. The foundation is sound and adheres to the specified architectural principles. The repository is now in an excellent state to begin the primary work of packaging applications.
+
+**This report concludes the foundational audit phase. The project is approved to move forward.**
+
+**Overall Grade: A+ (Excellent)**
+
+---
+
+## 2. Verification of Mandatory Cleanup
+
+A point-by-point confirmation of the tasks from the `FIX-1.md` prompt.
+
+| Task | Status | Verification Notes |
+|---|---|---|
+| **1a. Clean Repository Files** | **PASS** | The `Makefile` and all old, complex host scripts (`scripts/run_dev.sh`, `scripts/ci_local.sh`, etc.) have been successfully deleted. |
+| **1b. Move `requirements.txt`** | **PASS** | The file was correctly moved to `docker/devtools/requirements.txt`. |
+| **2. Fix `devtools` Dockerfile** | **PASS** | The `Dockerfile` now correctly copies the `requirements.txt` file from its new location, making the `devtools` image buildable. |
+| **3. Create Orchestration Scripts** | **PASS** | The `run/` directory and its scripts (`dev.sh`, `packager.sh`) were created with the exact content specified. The orchestration layer is now compliant and functional. |
+| **4. Fix Manifest Template** | **PASS** | The `memoryLimit` placeholder was added back to the `CloudronManifest.json.j2` template with the required guiding comment. This resolves a critical packaging risk. |
+| **5. Rewrite Documentation** | **PASS** | The main `README.md` has been updated to exclusively feature the new, correct workflow using the `run/*.sh` scripts. |
+
+---
+
+## 3. Remaining Minor Recommendations
+
+With the major foundational issues resolved, only minor points remain. These can be addressed as part of ongoing work.
+
+*   **Dockerfile Template:** The `Dockerfile.j2` template could be slightly improved by removing the `COPY ./app /app/code` line entirely. This would force the developer to write a proper `COPY --from=builder ...` command, reinforcing the multi-stage build pattern.
+*   **Full Documentation Sync:** While the main `README.md` is correct, a pass should be taken through the `docs/` directory at a later date to ensure all deeper documentation also reflects the new `run/*.sh` workflow.
+
+---
+
+## 4. Conclusion
+
+The repository is now in an exemplary state. The combination of a robust, containerized toolchain and a simple, clear orchestration layer provides a solid foundation for the complex task of packaging dozens of applications.
+
+The project is ready to proceed with its primary mission.

GEMINI/FIX-1.md

@@ -0,0 +1,16 @@
+You will now perform a mandatory cleanup of this repository. Your sole focus is to implement the **exact** instructions outlined in the "Final Actionable Mandate" section of `GEMINI/AUDIT-SNAPSHOT2.md`.
+
+**Your task is to:**
+
+1.  **Execute every command** listed in "Step 1: Clean the Repository" to remove the incorrect files.
+2.  **Execute the command** in "Step 1" to move `requirements.txt` to the correct location.
+3.  **Execute the command** in "Step 2" to fix the `docker/devtools/Dockerfile`.
+4.  **Create the `run/` directory and the two shell scripts** (`run/dev.sh`, `run/packager.sh`) using the **exact code** provided in "Step 3: Create the Correct Orchestration Scripts".
+5.  **Fix the manifest template** (`templates/cloudron-app/CloudronManifest.json.j2`) by adding the `memoryLimit` placeholder exactly as shown in "Step 4: Fix the Manifest Template".
+6.  **Rewrite the `README.md`** as described in "Step 5: Rewrite All Documentation", replacing the "Quick start" section with instructions that exclusively use the new `run/dev.sh` and `run/packager.sh` scripts for all development tasks.
+
+**DO NOT** deviate from this plan.
+**DO NOT** introduce any new files or scripts other than those specified.
+**DO NOT** leave any of the old, incorrect files (`Makefile`, etc.) in the repository.
+
+Your goal is not to be creative; your goal is to follow the provided recovery plan precisely.

Makefile

@@ -1,16 +0,0 @@
-.PHONY: scaffold lint status packager-shell
-
-scaffold:
-	python3 scripts/new_app.py --force
-
-lint:
-	python3 scripts/lint_repo.py
-
-status:
-	python3 scripts/generate_status.py
-
-packager-shell:
-	BUILD=1 scripts/run_packager.sh
-
-ci-local:
-	./scripts/ci_local.sh all

README.md

@@ -10,47 +10,41 @@ This repository scaffolds Cloudron packages for Known Element's portfolio. It pr
 ## Quick start
 
 ```bash
-# Generate all app scaffolds from the catalog
+# Build or refresh the devtools image (first run builds automatically)
-python3 scripts/new_app.py
+./run/dev.sh python --version
 
-# Or regenerate scaffolds via Makefile
+# Generate or refresh a single app scaffold
-make scaffold
+./run/dev.sh python scripts/new_app.py --slug apache-apisix
 
-# Work on a single app skeleton
+# Regenerate every scaffold (overwrites existing directories)
-python3 scripts/new_app.py --slug apache-apisix
+./run/dev.sh python scripts/new_app.py --force
 
-# Update the status table
+# Lint an app and fail on placeholders
-make status
+./run/dev.sh python scripts/lint_repo.py --slug apache-apisix --strict
 
-# Lint generated apps
+# Update the status dashboard
-make lint
+./run/dev.sh python scripts/generate_status.py --preserve-timestamp
-
-# Run the full CI harness locally
-make ci-local
-
-# Build and enter the Cloudron packager container
-BUILD=1 scripts/run_packager.sh
-scripts/run_packager.sh
 ```
 
-Within the container, use the Cloudron CLI to build, test, and publish packages without touching the host environment:
+### Packaging shell
 
 ```bash
-cloudron login my.example.cloudron
+# Build the Cloudron packager image (run when Dockerfile changes)
-cloudron build
+BUILD=1 ./run/packager.sh
-cloudron install --app my-example
+
-cloudron push
+# Launch an interactive Cloudron packaging shell
+./run/packager.sh
 ```
 
-Refer to `docs/PACKAGING_GUIDE.md` for detailed guidance.
+All other development tasks should also use `./run/dev.sh` (pass the desired command after the script). The wrapper will build the devtools image if needed and ensure every command executes inside Docker.
 
-See `docs/APP_STATUS.md` for the automatically generated status table.
 
 ## Repository layout
 
 - `apps/` – generated app scaffolds and metadata
 - `docs/` – playbooks and architecture notes
 - `docs/CI_CD_GITEA.md` – instructions for running CI/CD and publishing images via the Gitea instance
+- `docker/devtools/` – Docker image that runs scaffolding, linting, and status tooling
 - `docker/packager/` – Docker image for Cloudron packaging workflows
 - `scripts/` – helper scripts (scaffolding, tooling entrypoints)
 - `templates/` – base Cloudron app template
@@ -118,11 +112,30 @@ See `docs/APP_STATUS.md` for the automatically generated status table.
 All entries are initially marked as `todo`; update individual READMEs as progress is made.
 
 
-## Local Harness
+## Local Verification
 
-Run `./scripts/ci_local.sh` (or `make ci-local`) to execute the same lint and smoke tests that the future Gitea runner will use. Install git hooks via `./scripts/hooks/install_hooks.sh` so pre-commit, post-commit, and pre-push events invoke the harness automatically. Export `SKIP_CI_HOOKS=1` to bypass them when necessary. See `docs/LOCAL_TESTING.md` for full details.
+Run quality checks via the devtools wrapper:
+
+```bash
+# Fail if placeholders remain in the target manifest/start script
+./run/dev.sh python scripts/lint_repo.py --slug apache-apisix --strict
+
+# Refresh docs/APP_STATUS.md without changing the existing timestamp
+./run/dev.sh python scripts/generate_status.py --preserve-timestamp
+```
+
+Use `./run/packager.sh` whenever you need the Cloudron CLI to build, install, or push packages—it drops you into the dedicated packaging container.
 
 ## CI/CD
 
-Once a runner is provisioned, enable `.gitea/workflows/ci.yml` to call the same harness remotely (it currently requires manual `workflow_dispatch`). Mirror `actions/checkout@v4` and label the runner `ubuntu-22.04`. See `docs/CI_CD_GITEA.md` for setup details.
+The workflow `.gitea/workflows/ci.yml` mirrors the same commands by invoking the devtools container inside the runner. To reproduce the pipeline locally, run:
 
+```bash
+./run/dev.sh python scripts/lint_repo.py --strict --slug apache-apisix
+./run/dev.sh python scripts/generate_status.py --preserve-timestamp
+BUILD=1 ./run/packager.sh    # optional: rebuild packager image before smoke tests
+```
+
+Once a Gitea Actions runner is available, enable the workflow and it will build `knel/cloudron-devtools`/`knel/cloudron-ci` automatically.
+
+Refer to `docs/PACKAGING_GUIDE.md` and `AGENTS.md` for detailed operating procedures.

apps/apache-apisix/CloudronManifest.json

@@ -12,9 +12,16 @@
   "version": "0.1.0",
   "tags": ["custom", "known-element"],
   "healthCheckPath": "/",
-  "memoryLimit": 536870912,
   "httpPort": 3000,
+  "memoryLimit": "512M",
   "addons": {
     "localstorage": {}
+  },
+  "optionalAddons": {
+    "postgresql": {},
+    "redis": {},
+    "mysql": {},
+    "mongodb": {},
+    "sendmail": {}
   }
 }

apps/apache-apisix/Dockerfile

@@ -1,21 +1,38 @@
-# syntax=docker/dockerfile:1
+# syntax=docker/dockerfile:1.6
-FROM cloudron/base:5.0.0
 
+ARG APP_VERSION=latest
+
+FROM cloudron/base:5.0.0 AS builder
+WORKDIR /build
+
+# -----------------------------------------------------------------------------
+# TODO: Fetch and build Apache APISIX
+# Example:
+# RUN git clone --depth 1 --branch "${APP_VERSION}" https://github.com/apache/apisix.git source \
+#     && cd source \
+#     && npm ci \
+#     && npm run build
+# -----------------------------------------------------------------------------
+
+FROM cloudron/base:5.0.0
 LABEL org.opencontainers.image.source="https://github.com/apache/apisix.git"
 LABEL org.opencontainers.image.description="Cloudron package for Apache APISIX"
 
-ARG APP_VERSION
+ENV APP_VERSION=${APP_VERSION}
-ENV APP_VERSION=${APP_VERSION:-latest}
+
+# -----------------------------------------------------------------------------
+# TODO: Copy build artefacts from the builder stage
+# COPY --from=builder /build/source/dist /app/code
+# -----------------------------------------------------------------------------
 
-# Copy application source into image at build time
-# Replace this with a multi-stage build if upstream provides Docker images.
 COPY ./app /app/code
-
-# Copy start script and make it executable
 COPY ./start.sh /app/pkg/start.sh
-RUN chmod +x /app/pkg/start.sh
+COPY ./test /app/pkg/test
+
+RUN chmod +x /app/pkg/start.sh /app/pkg/test/smoke.sh \
+    && mkdir -p /app/data \
+    && chown -R cloudron:cloudron /app
 
-# Cloudron expects all processes to run as cloudron user
 USER cloudron
 WORKDIR /app/code
 

apps/apache-apisix/README.md

@@ -2,19 +2,19 @@
 
 - **Upstream repository**: https://github.com/apache/apisix.git
 - **Implementation issue**: https://projects.knownelement.com/issues/179
-- **Status**: Draft scaffolding generated on $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+- **Generated**: 2025-10-02T17:19:00Z UTC
 
 ## Packaging Checklist
 
-1. Review upstream deployment requirements and map them to Cloudron services (database, cache, object storage, workers).
+1. Map upstream services (databases, caches, workers) to Cloudron addons; remove unused entries from `optionalAddons` and enable required ones under `addons`.
-2. Update `Dockerfile` with the correct build steps and runtime dependencies.
+2. Implement the multi-stage build in `Dockerfile` to fetch/compile the correct release of Apache APISIX.
-3. Implement `start.sh` to configure the app from Cloudron-provided environment variables and launch the primary process.
+3. Update `start.sh` to configure the app from Cloudron environment variables and launch the primary process.
-4. Edit `CloudronManifest.json` with accurate metadata, permissions, ports, addons, and health checks.
+4. Replace the placeholder health checks and smoke test with real coverage.
-5. Add integration and smoke tests under `test/` to validate the package.
+5. Complete `CloudronManifest.json` (tagline, description, versioning, resource limits, ingress, TCP ports, etc.).
-6. Document manual configuration steps, migration requirements, and known gaps in this README.
+6. Document manual configuration steps, migrations, and known gaps below.
 
 ## Notes
 
-- Replace the placeholder long-running process in `start.sh`.
+- Populate the `app/` directory with runtime overlays or artifacts generated during the build stage.
-- Populate the `app/` directory with the application build artefacts or git submodules.
+- Use the shared packaging container (`docker/packager`) for `cloudron build/install` to keep the host clean.
-- Use the shared packaging container (`docker/packager`) to run `cloudron build` and `cloudron install` so the host remains clean.
+- Record decisions and operational requirements under `docs/apps/apache-apisix/` as work progresses.

apps/apache-apisix/metadata.json

@@ -4,6 +4,6 @@
   "issue": "https://projects.knownelement.com/issues/179",
   "repo": "https://github.com/apache/apisix.git",
   "additionalRepos": [],
-  "created": "2025-10-02T16:46:49Z",
+  "created": "2025-10-02T17:19:00Z",
   "notes": "TODO: capture packaging notes"
 }

apps/apache-apisix/start.sh

@@ -1,8 +1,9 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Cloudron injects configuration via environment variables and files under /run
+# TODO: render configuration files from CLOUDRON_* environment variables
-# Use this script to render config files and launch the upstream service.
+# Example:
+#   envsubst < /app/pkg/config.tmpl > /run/config.yaml
 
-# TODO: Replace the command below with the correct process supervisor.
+>&2 echo "start.sh for Apache APISIX is not implemented yet."
-exec /bin/sh -c "echo 'Replace start.sh with application startup logic for Apache APISIX' && sleep infinity"
+exit 1

apps/apache-apisix/test/smoke.sh

@@ -1,16 +1,14 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Basic container reachability check executed inside the packaging container.
+cloudron_app_origin=${CLOUDRON_APP_ORIGIN:-http://localhost}
-# Replace curl target with an endpoint exposed by the app once the package is functional.
-cloudron_app_url=${CLOUDRON_APP_ORIGIN:-"http://localhost"}
 
-http_code=$(curl -s -o /tmp/smoke.log -w "%{http_code}" "${cloudron_app_url}")
+http_code=$(curl --silent --show-error --output /tmp/smoke.log --write-out "%{http_code}" "${cloudron_app_origin}/")
 
 if [[ "${http_code}" != "200" ]]; then
-  echo "Unexpected HTTP status: ${http_code}" >&2
+  >&2 echo "Smoke test failed for Apache APISIX: expected HTTP 200 from ${cloudron_app_origin}/, got ${http_code}"
-  cat /tmp/smoke.log >&2
+  >&2 cat /tmp/smoke.log
   exit 1
 fi
 
-echo "Smoke test passed"
+echo "Smoke test placeholder passed for Apache APISIX"

apps/autobom/CloudronManifest.json

@@ -12,9 +12,16 @@
   "version": "0.1.0",
   "tags": ["custom", "known-element"],
   "healthCheckPath": "/",
-  "memoryLimit": 536870912,
   "httpPort": 3000,
+  "memoryLimit": "512M",
   "addons": {
     "localstorage": {}
+  },
+  "optionalAddons": {
+    "postgresql": {},
+    "redis": {},
+    "mysql": {},
+    "mongodb": {},
+    "sendmail": {}
   }
 }

apps/autobom/Dockerfile

@@ -1,21 +1,38 @@
-# syntax=docker/dockerfile:1
+# syntax=docker/dockerfile:1.6
-FROM cloudron/base:5.0.0
 
+ARG APP_VERSION=latest
+
+FROM cloudron/base:5.0.0 AS builder
+WORKDIR /build
+
+# -----------------------------------------------------------------------------
+# TODO: Fetch and build Autobom
+# Example:
+# RUN git clone --depth 1 --branch "${APP_VERSION}" https://github.com/opulo-inc/autobom.git source \
+#     && cd source \
+#     && npm ci \
+#     && npm run build
+# -----------------------------------------------------------------------------
+
+FROM cloudron/base:5.0.0
 LABEL org.opencontainers.image.source="https://github.com/opulo-inc/autobom.git"
 LABEL org.opencontainers.image.description="Cloudron package for Autobom"
 
-ARG APP_VERSION
+ENV APP_VERSION=${APP_VERSION}
-ENV APP_VERSION=${APP_VERSION:-latest}
+
+# -----------------------------------------------------------------------------
+# TODO: Copy build artefacts from the builder stage
+# COPY --from=builder /build/source/dist /app/code
+# -----------------------------------------------------------------------------
 
-# Copy application source into image at build time
-# Replace this with a multi-stage build if upstream provides Docker images.
 COPY ./app /app/code
-
-# Copy start script and make it executable
 COPY ./start.sh /app/pkg/start.sh
-RUN chmod +x /app/pkg/start.sh
+COPY ./test /app/pkg/test
+
+RUN chmod +x /app/pkg/start.sh /app/pkg/test/smoke.sh \
+    && mkdir -p /app/data \
+    && chown -R cloudron:cloudron /app
 
-# Cloudron expects all processes to run as cloudron user
 USER cloudron
 WORKDIR /app/code
 

apps/autobom/README.md

@@ -2,19 +2,19 @@
 
 - **Upstream repository**: https://github.com/opulo-inc/autobom.git
 - **Implementation issue**: https://projects.knownelement.com/issues/278
-- **Status**: Draft scaffolding generated on $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+- **Generated**: 2025-10-02T17:19:01Z UTC
 
 ## Packaging Checklist
 
-1. Review upstream deployment requirements and map them to Cloudron services (database, cache, object storage, workers).
+1. Map upstream services (databases, caches, workers) to Cloudron addons; remove unused entries from `optionalAddons` and enable required ones under `addons`.
-2. Update `Dockerfile` with the correct build steps and runtime dependencies.
+2. Implement the multi-stage build in `Dockerfile` to fetch/compile the correct release of Autobom.
-3. Implement `start.sh` to configure the app from Cloudron-provided environment variables and launch the primary process.
+3. Update `start.sh` to configure the app from Cloudron environment variables and launch the primary process.
-4. Edit `CloudronManifest.json` with accurate metadata, permissions, ports, addons, and health checks.
+4. Replace the placeholder health checks and smoke test with real coverage.
-5. Add integration and smoke tests under `test/` to validate the package.
+5. Complete `CloudronManifest.json` (tagline, description, versioning, resource limits, ingress, TCP ports, etc.).
-6. Document manual configuration steps, migration requirements, and known gaps in this README.
+6. Document manual configuration steps, migrations, and known gaps below.
 
 ## Notes
 
-- Replace the placeholder long-running process in `start.sh`.
+- Populate the `app/` directory with runtime overlays or artifacts generated during the build stage.
-- Populate the `app/` directory with the application build artefacts or git submodules.
+- Use the shared packaging container (`docker/packager`) for `cloudron build/install` to keep the host clean.
-- Use the shared packaging container (`docker/packager`) to run `cloudron build` and `cloudron install` so the host remains clean.
+- Record decisions and operational requirements under `docs/apps/autobom/` as work progresses.

apps/autobom/metadata.json

@@ -4,6 +4,6 @@
   "issue": "https://projects.knownelement.com/issues/278",
   "repo": "https://github.com/opulo-inc/autobom.git",
   "additionalRepos": [],
-  "created": "2025-10-02T16:46:49Z",
+  "created": "2025-10-02T17:19:01Z",
   "notes": "TODO: capture packaging notes"
 }

apps/autobom/start.sh

@@ -1,8 +1,9 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Cloudron injects configuration via environment variables and files under /run
+# TODO: render configuration files from CLOUDRON_* environment variables
-# Use this script to render config files and launch the upstream service.
+# Example:
+#   envsubst < /app/pkg/config.tmpl > /run/config.yaml
 
-# TODO: Replace the command below with the correct process supervisor.
+>&2 echo "start.sh for Autobom is not implemented yet."
-exec /bin/sh -c "echo 'Replace start.sh with application startup logic for Autobom' && sleep infinity"
+exit 1

apps/autobom/test/smoke.sh

@@ -1,16 +1,14 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Basic container reachability check executed inside the packaging container.
+cloudron_app_origin=${CLOUDRON_APP_ORIGIN:-http://localhost}
-# Replace curl target with an endpoint exposed by the app once the package is functional.
-cloudron_app_url=${CLOUDRON_APP_ORIGIN:-"http://localhost"}
 
-http_code=$(curl -s -o /tmp/smoke.log -w "%{http_code}" "${cloudron_app_url}")
+http_code=$(curl --silent --show-error --output /tmp/smoke.log --write-out "%{http_code}" "${cloudron_app_origin}/")
 
 if [[ "${http_code}" != "200" ]]; then
-  echo "Unexpected HTTP status: ${http_code}" >&2
+  >&2 echo "Smoke test failed for Autobom: expected HTTP 200 from ${cloudron_app_origin}/, got ${http_code}"
-  cat /tmp/smoke.log >&2
+  >&2 cat /tmp/smoke.log
   exit 1
 fi
 
-echo "Smoke test passed"
+echo "Smoke test placeholder passed for Autobom"

apps/chirpstack/CloudronManifest.json

@@ -12,9 +12,16 @@
   "version": "0.1.0",
   "tags": ["custom", "known-element"],
   "healthCheckPath": "/",
-  "memoryLimit": 536870912,
   "httpPort": 3000,
+  "memoryLimit": "512M",
   "addons": {
     "localstorage": {}
+  },
+  "optionalAddons": {
+    "postgresql": {},
+    "redis": {},
+    "mysql": {},
+    "mongodb": {},
+    "sendmail": {}
   }
 }

apps/chirpstack/Dockerfile

@@ -1,21 +1,38 @@
-# syntax=docker/dockerfile:1
+# syntax=docker/dockerfile:1.6
-FROM cloudron/base:5.0.0
 
+ARG APP_VERSION=latest
+
+FROM cloudron/base:5.0.0 AS builder
+WORKDIR /build
+
+# -----------------------------------------------------------------------------
+# TODO: Fetch and build ChirpStack
+# Example:
+# RUN git clone --depth 1 --branch "${APP_VERSION}" https://github.com/chirpstack/chirpstack.git source \
+#     && cd source \
+#     && npm ci \
+#     && npm run build
+# -----------------------------------------------------------------------------
+
+FROM cloudron/base:5.0.0
 LABEL org.opencontainers.image.source="https://github.com/chirpstack/chirpstack.git"
 LABEL org.opencontainers.image.description="Cloudron package for ChirpStack"
 
-ARG APP_VERSION
+ENV APP_VERSION=${APP_VERSION}
-ENV APP_VERSION=${APP_VERSION:-latest}
+
+# -----------------------------------------------------------------------------
+# TODO: Copy build artefacts from the builder stage
+# COPY --from=builder /build/source/dist /app/code
+# -----------------------------------------------------------------------------
 
-# Copy application source into image at build time
-# Replace this with a multi-stage build if upstream provides Docker images.
 COPY ./app /app/code
-
-# Copy start script and make it executable
 COPY ./start.sh /app/pkg/start.sh
-RUN chmod +x /app/pkg/start.sh
+COPY ./test /app/pkg/test
+
+RUN chmod +x /app/pkg/start.sh /app/pkg/test/smoke.sh \
+    && mkdir -p /app/data \
+    && chown -R cloudron:cloudron /app
 
-# Cloudron expects all processes to run as cloudron user
 USER cloudron
 WORKDIR /app/code
 

apps/chirpstack/README.md

@@ -2,19 +2,19 @@
 
 - **Upstream repository**: https://github.com/chirpstack/chirpstack.git
 - **Implementation issue**: https://projects.knownelement.com/issues/184
-- **Status**: Draft scaffolding generated on $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+- **Generated**: 2025-10-02T17:19:00Z UTC
 
 ## Packaging Checklist
 
-1. Review upstream deployment requirements and map them to Cloudron services (database, cache, object storage, workers).
+1. Map upstream services (databases, caches, workers) to Cloudron addons; remove unused entries from `optionalAddons` and enable required ones under `addons`.
-2. Update `Dockerfile` with the correct build steps and runtime dependencies.
+2. Implement the multi-stage build in `Dockerfile` to fetch/compile the correct release of ChirpStack.
-3. Implement `start.sh` to configure the app from Cloudron-provided environment variables and launch the primary process.
+3. Update `start.sh` to configure the app from Cloudron environment variables and launch the primary process.
-4. Edit `CloudronManifest.json` with accurate metadata, permissions, ports, addons, and health checks.
+4. Replace the placeholder health checks and smoke test with real coverage.
-5. Add integration and smoke tests under `test/` to validate the package.
+5. Complete `CloudronManifest.json` (tagline, description, versioning, resource limits, ingress, TCP ports, etc.).
-6. Document manual configuration steps, migration requirements, and known gaps in this README.
+6. Document manual configuration steps, migrations, and known gaps below.
 
 ## Notes
 
-- Replace the placeholder long-running process in `start.sh`.
+- Populate the `app/` directory with runtime overlays or artifacts generated during the build stage.
-- Populate the `app/` directory with the application build artefacts or git submodules.
+- Use the shared packaging container (`docker/packager`) for `cloudron build/install` to keep the host clean.
-- Use the shared packaging container (`docker/packager`) to run `cloudron build` and `cloudron install` so the host remains clean.
+- Record decisions and operational requirements under `docs/apps/chirpstack/` as work progresses.

apps/chirpstack/metadata.json

@@ -4,6 +4,6 @@
   "issue": "https://projects.knownelement.com/issues/184",
   "repo": "https://github.com/chirpstack/chirpstack.git",
   "additionalRepos": [],
-  "created": "2025-10-02T16:46:49Z",
+  "created": "2025-10-02T17:19:00Z",
   "notes": "TODO: capture packaging notes"
 }

apps/chirpstack/start.sh

@@ -1,8 +1,9 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Cloudron injects configuration via environment variables and files under /run
+# TODO: render configuration files from CLOUDRON_* environment variables
-# Use this script to render config files and launch the upstream service.
+# Example:
+#   envsubst < /app/pkg/config.tmpl > /run/config.yaml
 
-# TODO: Replace the command below with the correct process supervisor.
+>&2 echo "start.sh for ChirpStack is not implemented yet."
-exec /bin/sh -c "echo 'Replace start.sh with application startup logic for ChirpStack' && sleep infinity"
+exit 1

apps/chirpstack/test/smoke.sh

@@ -1,16 +1,14 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Basic container reachability check executed inside the packaging container.
+cloudron_app_origin=${CLOUDRON_APP_ORIGIN:-http://localhost}
-# Replace curl target with an endpoint exposed by the app once the package is functional.
-cloudron_app_url=${CLOUDRON_APP_ORIGIN:-"http://localhost"}
 
-http_code=$(curl -s -o /tmp/smoke.log -w "%{http_code}" "${cloudron_app_url}")
+http_code=$(curl --silent --show-error --output /tmp/smoke.log --write-out "%{http_code}" "${cloudron_app_origin}/")
 
 if [[ "${http_code}" != "200" ]]; then
-  echo "Unexpected HTTP status: ${http_code}" >&2
+  >&2 echo "Smoke test failed for ChirpStack: expected HTTP 200 from ${cloudron_app_origin}/, got ${http_code}"
-  cat /tmp/smoke.log >&2
+  >&2 cat /tmp/smoke.log
   exit 1
 fi
 
-echo "Smoke test passed"
+echo "Smoke test placeholder passed for ChirpStack"

apps/consuldemocracy/CloudronManifest.json

@@ -12,9 +12,16 @@
   "version": "0.1.0",
   "tags": ["custom", "known-element"],
   "healthCheckPath": "/",
-  "memoryLimit": 536870912,
   "httpPort": 3000,
+  "memoryLimit": "512M",
   "addons": {
     "localstorage": {}
+  },
+  "optionalAddons": {
+    "postgresql": {},
+    "redis": {},
+    "mysql": {},
+    "mongodb": {},
+    "sendmail": {}
   }
 }

apps/consuldemocracy/Dockerfile

@@ -1,21 +1,38 @@
-# syntax=docker/dockerfile:1
+# syntax=docker/dockerfile:1.6
-FROM cloudron/base:5.0.0
 
+ARG APP_VERSION=latest
+
+FROM cloudron/base:5.0.0 AS builder
+WORKDIR /build
+
+# -----------------------------------------------------------------------------
+# TODO: Fetch and build CONSUL Democracy
+# Example:
+# RUN git clone --depth 1 --branch "${APP_VERSION}" https://github.com/consuldemocracy/consuldemocracy.git source \
+#     && cd source \
+#     && npm ci \
+#     && npm run build
+# -----------------------------------------------------------------------------
+
+FROM cloudron/base:5.0.0
 LABEL org.opencontainers.image.source="https://github.com/consuldemocracy/consuldemocracy.git"
 LABEL org.opencontainers.image.description="Cloudron package for CONSUL Democracy"
 
-ARG APP_VERSION
+ENV APP_VERSION=${APP_VERSION}
-ENV APP_VERSION=${APP_VERSION:-latest}
+
+# -----------------------------------------------------------------------------
+# TODO: Copy build artefacts from the builder stage
+# COPY --from=builder /build/source/dist /app/code
+# -----------------------------------------------------------------------------
 
-# Copy application source into image at build time
-# Replace this with a multi-stage build if upstream provides Docker images.
 COPY ./app /app/code
-
-# Copy start script and make it executable
 COPY ./start.sh /app/pkg/start.sh
-RUN chmod +x /app/pkg/start.sh
+COPY ./test /app/pkg/test
+
+RUN chmod +x /app/pkg/start.sh /app/pkg/test/smoke.sh \
+    && mkdir -p /app/data \
+    && chown -R cloudron:cloudron /app
 
-# Cloudron expects all processes to run as cloudron user
 USER cloudron
 WORKDIR /app/code
 

apps/consuldemocracy/README.md

@@ -2,19 +2,19 @@
 
 - **Upstream repository**: https://github.com/consuldemocracy/consuldemocracy.git
 - **Implementation issue**: https://projects.knownelement.com/issues/189
-- **Status**: Draft scaffolding generated on $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+- **Generated**: 2025-10-02T17:19:00Z UTC
 
 ## Packaging Checklist
 
-1. Review upstream deployment requirements and map them to Cloudron services (database, cache, object storage, workers).
+1. Map upstream services (databases, caches, workers) to Cloudron addons; remove unused entries from `optionalAddons` and enable required ones under `addons`.
-2. Update `Dockerfile` with the correct build steps and runtime dependencies.
+2. Implement the multi-stage build in `Dockerfile` to fetch/compile the correct release of CONSUL Democracy.
-3. Implement `start.sh` to configure the app from Cloudron-provided environment variables and launch the primary process.
+3. Update `start.sh` to configure the app from Cloudron environment variables and launch the primary process.
-4. Edit `CloudronManifest.json` with accurate metadata, permissions, ports, addons, and health checks.
+4. Replace the placeholder health checks and smoke test with real coverage.
-5. Add integration and smoke tests under `test/` to validate the package.
+5. Complete `CloudronManifest.json` (tagline, description, versioning, resource limits, ingress, TCP ports, etc.).
-6. Document manual configuration steps, migration requirements, and known gaps in this README.
+6. Document manual configuration steps, migrations, and known gaps below.
 
 ## Notes
 
-- Replace the placeholder long-running process in `start.sh`.
+- Populate the `app/` directory with runtime overlays or artifacts generated during the build stage.
-- Populate the `app/` directory with the application build artefacts or git submodules.
+- Use the shared packaging container (`docker/packager`) for `cloudron build/install` to keep the host clean.
-- Use the shared packaging container (`docker/packager`) to run `cloudron build` and `cloudron install` so the host remains clean.
+- Record decisions and operational requirements under `docs/apps/consuldemocracy/` as work progresses.

apps/consuldemocracy/metadata.json

@@ -4,6 +4,6 @@
   "issue": "https://projects.knownelement.com/issues/189",
   "repo": "https://github.com/consuldemocracy/consuldemocracy.git",
   "additionalRepos": [],
-  "created": "2025-10-02T16:46:49Z",
+  "created": "2025-10-02T17:19:00Z",
   "notes": "TODO: capture packaging notes"
 }

apps/consuldemocracy/start.sh

@@ -1,8 +1,9 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Cloudron injects configuration via environment variables and files under /run
+# TODO: render configuration files from CLOUDRON_* environment variables
-# Use this script to render config files and launch the upstream service.
+# Example:
+#   envsubst < /app/pkg/config.tmpl > /run/config.yaml
 
-# TODO: Replace the command below with the correct process supervisor.
+>&2 echo "start.sh for CONSUL Democracy is not implemented yet."
-exec /bin/sh -c "echo 'Replace start.sh with application startup logic for CONSUL Democracy' && sleep infinity"
+exit 1

apps/consuldemocracy/test/smoke.sh

@@ -1,16 +1,14 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Basic container reachability check executed inside the packaging container.
+cloudron_app_origin=${CLOUDRON_APP_ORIGIN:-http://localhost}
-# Replace curl target with an endpoint exposed by the app once the package is functional.
-cloudron_app_url=${CLOUDRON_APP_ORIGIN:-"http://localhost"}
 
-http_code=$(curl -s -o /tmp/smoke.log -w "%{http_code}" "${cloudron_app_url}")
+http_code=$(curl --silent --show-error --output /tmp/smoke.log --write-out "%{http_code}" "${cloudron_app_origin}/")
 
 if [[ "${http_code}" != "200" ]]; then
-  echo "Unexpected HTTP status: ${http_code}" >&2
+  >&2 echo "Smoke test failed for CONSUL Democracy: expected HTTP 200 from ${cloudron_app_origin}/, got ${http_code}"
-  cat /tmp/smoke.log >&2
+  >&2 cat /tmp/smoke.log
   exit 1
 fi
 
-echo "Smoke test passed"
+echo "Smoke test placeholder passed for CONSUL Democracy"

apps/craig/CloudronManifest.json

@@ -12,9 +12,16 @@
   "version": "0.1.0",
   "tags": ["custom", "known-element"],
   "healthCheckPath": "/",
-  "memoryLimit": 536870912,
   "httpPort": 3000,
+  "memoryLimit": "512M",
   "addons": {
     "localstorage": {}
+  },
+  "optionalAddons": {
+    "postgresql": {},
+    "redis": {},
+    "mysql": {},
+    "mongodb": {},
+    "sendmail": {}
   }
 }

apps/craig/Dockerfile

@@ -1,21 +1,38 @@
-# syntax=docker/dockerfile:1
+# syntax=docker/dockerfile:1.6
-FROM cloudron/base:5.0.0
 
+ARG APP_VERSION=latest
+
+FROM cloudron/base:5.0.0 AS builder
+WORKDIR /build
+
+# -----------------------------------------------------------------------------
+# TODO: Fetch and build Craig (FOSS Discord Recorder)
+# Example:
+# RUN git clone --depth 1 --branch "${APP_VERSION}" https://github.com/CraigChat/craig.git source \
+#     && cd source \
+#     && npm ci \
+#     && npm run build
+# -----------------------------------------------------------------------------
+
+FROM cloudron/base:5.0.0
 LABEL org.opencontainers.image.source="https://github.com/CraigChat/craig.git"
 LABEL org.opencontainers.image.description="Cloudron package for Craig (FOSS Discord Recorder)"
 
-ARG APP_VERSION
+ENV APP_VERSION=${APP_VERSION}
-ENV APP_VERSION=${APP_VERSION:-latest}
+
+# -----------------------------------------------------------------------------
+# TODO: Copy build artefacts from the builder stage
+# COPY --from=builder /build/source/dist /app/code
+# -----------------------------------------------------------------------------
 
-# Copy application source into image at build time
-# Replace this with a multi-stage build if upstream provides Docker images.
 COPY ./app /app/code
-
-# Copy start script and make it executable
 COPY ./start.sh /app/pkg/start.sh
-RUN chmod +x /app/pkg/start.sh
+COPY ./test /app/pkg/test
+
+RUN chmod +x /app/pkg/start.sh /app/pkg/test/smoke.sh \
+    && mkdir -p /app/data \
+    && chown -R cloudron:cloudron /app
 
-# Cloudron expects all processes to run as cloudron user
 USER cloudron
 WORKDIR /app/code
 

apps/craig/README.md

@@ -2,19 +2,19 @@
 
 - **Upstream repository**: https://github.com/CraigChat/craig.git
 - **Implementation issue**: https://projects.knownelement.com/issues/185
-- **Status**: Draft scaffolding generated on $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+- **Generated**: 2025-10-02T17:19:00Z UTC
 
 ## Packaging Checklist
 
-1. Review upstream deployment requirements and map them to Cloudron services (database, cache, object storage, workers).
+1. Map upstream services (databases, caches, workers) to Cloudron addons; remove unused entries from `optionalAddons` and enable required ones under `addons`.
-2. Update `Dockerfile` with the correct build steps and runtime dependencies.
+2. Implement the multi-stage build in `Dockerfile` to fetch/compile the correct release of Craig (FOSS Discord Recorder).
-3. Implement `start.sh` to configure the app from Cloudron-provided environment variables and launch the primary process.
+3. Update `start.sh` to configure the app from Cloudron environment variables and launch the primary process.
-4. Edit `CloudronManifest.json` with accurate metadata, permissions, ports, addons, and health checks.
+4. Replace the placeholder health checks and smoke test with real coverage.
-5. Add integration and smoke tests under `test/` to validate the package.
+5. Complete `CloudronManifest.json` (tagline, description, versioning, resource limits, ingress, TCP ports, etc.).
-6. Document manual configuration steps, migration requirements, and known gaps in this README.
+6. Document manual configuration steps, migrations, and known gaps below.
 
 ## Notes
 
-- Replace the placeholder long-running process in `start.sh`.
+- Populate the `app/` directory with runtime overlays or artifacts generated during the build stage.
-- Populate the `app/` directory with the application build artefacts or git submodules.
+- Use the shared packaging container (`docker/packager`) for `cloudron build/install` to keep the host clean.
-- Use the shared packaging container (`docker/packager`) to run `cloudron build` and `cloudron install` so the host remains clean.
+- Record decisions and operational requirements under `docs/apps/craig/` as work progresses.

apps/craig/metadata.json

@@ -4,6 +4,6 @@
   "issue": "https://projects.knownelement.com/issues/185",
   "repo": "https://github.com/CraigChat/craig.git",
   "additionalRepos": [],
-  "created": "2025-10-02T16:46:49Z",
+  "created": "2025-10-02T17:19:00Z",
   "notes": "TODO: capture packaging notes"
 }

apps/craig/start.sh

@@ -1,8 +1,9 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Cloudron injects configuration via environment variables and files under /run
+# TODO: render configuration files from CLOUDRON_* environment variables
-# Use this script to render config files and launch the upstream service.
+# Example:
+#   envsubst < /app/pkg/config.tmpl > /run/config.yaml
 
-# TODO: Replace the command below with the correct process supervisor.
+>&2 echo "start.sh for Craig (FOSS Discord Recorder) is not implemented yet."
-exec /bin/sh -c "echo 'Replace start.sh with application startup logic for Craig (FOSS Discord Recorder)' && sleep infinity"
+exit 1

apps/craig/test/smoke.sh

@@ -1,16 +1,14 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Basic container reachability check executed inside the packaging container.
+cloudron_app_origin=${CLOUDRON_APP_ORIGIN:-http://localhost}
-# Replace curl target with an endpoint exposed by the app once the package is functional.
-cloudron_app_url=${CLOUDRON_APP_ORIGIN:-"http://localhost"}
 
-http_code=$(curl -s -o /tmp/smoke.log -w "%{http_code}" "${cloudron_app_url}")
+http_code=$(curl --silent --show-error --output /tmp/smoke.log --write-out "%{http_code}" "${cloudron_app_origin}/")
 
 if [[ "${http_code}" != "200" ]]; then
-  echo "Unexpected HTTP status: ${http_code}" >&2
+  >&2 echo "Smoke test failed for Craig (FOSS Discord Recorder): expected HTTP 200 from ${cloudron_app_origin}/, got ${http_code}"
-  cat /tmp/smoke.log >&2
+  >&2 cat /tmp/smoke.log
   exit 1
 fi
 
-echo "Smoke test passed"
+echo "Smoke test placeholder passed for Craig (FOSS Discord Recorder)"

apps/database-gateway/CloudronManifest.json

@@ -12,9 +12,16 @@
   "version": "0.1.0",
   "tags": ["custom", "known-element"],
   "healthCheckPath": "/",
-  "memoryLimit": 536870912,
   "httpPort": 3000,
+  "memoryLimit": "512M",
   "addons": {
     "localstorage": {}
+  },
+  "optionalAddons": {
+    "postgresql": {},
+    "redis": {},
+    "mysql": {},
+    "mongodb": {},
+    "sendmail": {}
   }
 }

apps/database-gateway/Dockerfile

@@ -1,21 +1,38 @@
-# syntax=docker/dockerfile:1
+# syntax=docker/dockerfile:1.6
-FROM cloudron/base:5.0.0
 
+ARG APP_VERSION=latest
+
+FROM cloudron/base:5.0.0 AS builder
+WORKDIR /build
+
+# -----------------------------------------------------------------------------
+# TODO: Fetch and build Database Gateway
+# Example:
+# RUN git clone --depth 1 --branch "${APP_VERSION}" https://github.com/kazhuravlev/database-gateway.git source \
+#     && cd source \
+#     && npm ci \
+#     && npm run build
+# -----------------------------------------------------------------------------
+
+FROM cloudron/base:5.0.0
 LABEL org.opencontainers.image.source="https://github.com/kazhuravlev/database-gateway.git"
 LABEL org.opencontainers.image.description="Cloudron package for Database Gateway"
 
-ARG APP_VERSION
+ENV APP_VERSION=${APP_VERSION}
-ENV APP_VERSION=${APP_VERSION:-latest}
+
+# -----------------------------------------------------------------------------
+# TODO: Copy build artefacts from the builder stage
+# COPY --from=builder /build/source/dist /app/code
+# -----------------------------------------------------------------------------
 
-# Copy application source into image at build time
-# Replace this with a multi-stage build if upstream provides Docker images.
 COPY ./app /app/code
-
-# Copy start script and make it executable
 COPY ./start.sh /app/pkg/start.sh
-RUN chmod +x /app/pkg/start.sh
+COPY ./test /app/pkg/test
+
+RUN chmod +x /app/pkg/start.sh /app/pkg/test/smoke.sh \
+    && mkdir -p /app/data \
+    && chown -R cloudron:cloudron /app
 
-# Cloudron expects all processes to run as cloudron user
 USER cloudron
 WORKDIR /app/code
 

apps/database-gateway/README.md

@@ -2,19 +2,19 @@
 
 - **Upstream repository**: https://github.com/kazhuravlev/database-gateway.git
 - **Implementation issue**: https://projects.knownelement.com/issues/273
-- **Status**: Draft scaffolding generated on $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+- **Generated**: 2025-10-02T17:19:00Z UTC
 
 ## Packaging Checklist
 
-1. Review upstream deployment requirements and map them to Cloudron services (database, cache, object storage, workers).
+1. Map upstream services (databases, caches, workers) to Cloudron addons; remove unused entries from `optionalAddons` and enable required ones under `addons`.
-2. Update `Dockerfile` with the correct build steps and runtime dependencies.
+2. Implement the multi-stage build in `Dockerfile` to fetch/compile the correct release of Database Gateway.
-3. Implement `start.sh` to configure the app from Cloudron-provided environment variables and launch the primary process.
+3. Update `start.sh` to configure the app from Cloudron environment variables and launch the primary process.
-4. Edit `CloudronManifest.json` with accurate metadata, permissions, ports, addons, and health checks.
+4. Replace the placeholder health checks and smoke test with real coverage.
-5. Add integration and smoke tests under `test/` to validate the package.
+5. Complete `CloudronManifest.json` (tagline, description, versioning, resource limits, ingress, TCP ports, etc.).
-6. Document manual configuration steps, migration requirements, and known gaps in this README.
+6. Document manual configuration steps, migrations, and known gaps below.
 
 ## Notes
 
-- Replace the placeholder long-running process in `start.sh`.
+- Populate the `app/` directory with runtime overlays or artifacts generated during the build stage.
-- Populate the `app/` directory with the application build artefacts or git submodules.
+- Use the shared packaging container (`docker/packager`) for `cloudron build/install` to keep the host clean.
-- Use the shared packaging container (`docker/packager`) to run `cloudron build` and `cloudron install` so the host remains clean.
+- Record decisions and operational requirements under `docs/apps/database-gateway/` as work progresses.

apps/database-gateway/metadata.json

@@ -4,6 +4,6 @@
   "issue": "https://projects.knownelement.com/issues/273",
   "repo": "https://github.com/kazhuravlev/database-gateway.git",
   "additionalRepos": [],
-  "created": "2025-10-02T16:46:49Z",
+  "created": "2025-10-02T17:19:00Z",
   "notes": "TODO: capture packaging notes"
 }

apps/database-gateway/start.sh

@@ -1,8 +1,9 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Cloudron injects configuration via environment variables and files under /run
+# TODO: render configuration files from CLOUDRON_* environment variables
-# Use this script to render config files and launch the upstream service.
+# Example:
+#   envsubst < /app/pkg/config.tmpl > /run/config.yaml
 
-# TODO: Replace the command below with the correct process supervisor.
+>&2 echo "start.sh for Database Gateway is not implemented yet."
-exec /bin/sh -c "echo 'Replace start.sh with application startup logic for Database Gateway' && sleep infinity"
+exit 1

apps/database-gateway/test/smoke.sh

@@ -1,16 +1,14 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Basic container reachability check executed inside the packaging container.
+cloudron_app_origin=${CLOUDRON_APP_ORIGIN:-http://localhost}
-# Replace curl target with an endpoint exposed by the app once the package is functional.
-cloudron_app_url=${CLOUDRON_APP_ORIGIN:-"http://localhost"}
 
-http_code=$(curl -s -o /tmp/smoke.log -w "%{http_code}" "${cloudron_app_url}")
+http_code=$(curl --silent --show-error --output /tmp/smoke.log --write-out "%{http_code}" "${cloudron_app_origin}/")
 
 if [[ "${http_code}" != "200" ]]; then
-  echo "Unexpected HTTP status: ${http_code}" >&2
+  >&2 echo "Smoke test failed for Database Gateway: expected HTTP 200 from ${cloudron_app_origin}/, got ${http_code}"
-  cat /tmp/smoke.log >&2
+  >&2 cat /tmp/smoke.log
   exit 1
 fi
 
-echo "Smoke test passed"
+echo "Smoke test placeholder passed for Database Gateway"

apps/datahub/CloudronManifest.json

@@ -12,9 +12,16 @@
   "version": "0.1.0",
   "tags": ["custom", "known-element"],
   "healthCheckPath": "/",
-  "memoryLimit": 536870912,
   "httpPort": 3000,
+  "memoryLimit": "512M",
   "addons": {
     "localstorage": {}
+  },
+  "optionalAddons": {
+    "postgresql": {},
+    "redis": {},
+    "mysql": {},
+    "mongodb": {},
+    "sendmail": {}
   }
 }

apps/datahub/Dockerfile

@@ -1,21 +1,38 @@
-# syntax=docker/dockerfile:1
+# syntax=docker/dockerfile:1.6
-FROM cloudron/base:5.0.0
 
+ARG APP_VERSION=latest
+
+FROM cloudron/base:5.0.0 AS builder
+WORKDIR /build
+
+# -----------------------------------------------------------------------------
+# TODO: Fetch and build DataHub
+# Example:
+# RUN git clone --depth 1 --branch "${APP_VERSION}" https://github.com/datahub-project/datahub.git source \
+#     && cd source \
+#     && npm ci \
+#     && npm run build
+# -----------------------------------------------------------------------------
+
+FROM cloudron/base:5.0.0
 LABEL org.opencontainers.image.source="https://github.com/datahub-project/datahub.git"
 LABEL org.opencontainers.image.description="Cloudron package for DataHub"
 
-ARG APP_VERSION
+ENV APP_VERSION=${APP_VERSION}
-ENV APP_VERSION=${APP_VERSION:-latest}
+
+# -----------------------------------------------------------------------------
+# TODO: Copy build artefacts from the builder stage
+# COPY --from=builder /build/source/dist /app/code
+# -----------------------------------------------------------------------------
 
-# Copy application source into image at build time
-# Replace this with a multi-stage build if upstream provides Docker images.
 COPY ./app /app/code
-
-# Copy start script and make it executable
 COPY ./start.sh /app/pkg/start.sh
-RUN chmod +x /app/pkg/start.sh
+COPY ./test /app/pkg/test
+
+RUN chmod +x /app/pkg/start.sh /app/pkg/test/smoke.sh \
+    && mkdir -p /app/data \
+    && chown -R cloudron:cloudron /app
 
-# Cloudron expects all processes to run as cloudron user
 USER cloudron
 WORKDIR /app/code
 

apps/datahub/README.md

@@ -2,19 +2,19 @@
 
 - **Upstream repository**: https://github.com/datahub-project/datahub.git
 - **Implementation issue**: https://projects.knownelement.com/issues/309
-- **Status**: Draft scaffolding generated on $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+- **Generated**: 2025-10-02T17:19:00Z UTC
 
 ## Packaging Checklist
 
-1. Review upstream deployment requirements and map them to Cloudron services (database, cache, object storage, workers).
+1. Map upstream services (databases, caches, workers) to Cloudron addons; remove unused entries from `optionalAddons` and enable required ones under `addons`.
-2. Update `Dockerfile` with the correct build steps and runtime dependencies.
+2. Implement the multi-stage build in `Dockerfile` to fetch/compile the correct release of DataHub.
-3. Implement `start.sh` to configure the app from Cloudron-provided environment variables and launch the primary process.
+3. Update `start.sh` to configure the app from Cloudron environment variables and launch the primary process.
-4. Edit `CloudronManifest.json` with accurate metadata, permissions, ports, addons, and health checks.
+4. Replace the placeholder health checks and smoke test with real coverage.
-5. Add integration and smoke tests under `test/` to validate the package.
+5. Complete `CloudronManifest.json` (tagline, description, versioning, resource limits, ingress, TCP ports, etc.).
-6. Document manual configuration steps, migration requirements, and known gaps in this README.
+6. Document manual configuration steps, migrations, and known gaps below.
 
 ## Notes
 
-- Replace the placeholder long-running process in `start.sh`.
+- Populate the `app/` directory with runtime overlays or artifacts generated during the build stage.
-- Populate the `app/` directory with the application build artefacts or git submodules.
+- Use the shared packaging container (`docker/packager`) for `cloudron build/install` to keep the host clean.
-- Use the shared packaging container (`docker/packager`) to run `cloudron build` and `cloudron install` so the host remains clean.
+- Record decisions and operational requirements under `docs/apps/datahub/` as work progresses.

apps/datahub/metadata.json

@@ -4,6 +4,6 @@
   "issue": "https://projects.knownelement.com/issues/309",
   "repo": "https://github.com/datahub-project/datahub.git",
   "additionalRepos": [],
-  "created": "2025-10-02T16:46:49Z",
+  "created": "2025-10-02T17:19:00Z",
   "notes": "TODO: capture packaging notes"
 }

apps/datahub/start.sh

@@ -1,8 +1,9 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Cloudron injects configuration via environment variables and files under /run
+# TODO: render configuration files from CLOUDRON_* environment variables
-# Use this script to render config files and launch the upstream service.
+# Example:
+#   envsubst < /app/pkg/config.tmpl > /run/config.yaml
 
-# TODO: Replace the command below with the correct process supervisor.
+>&2 echo "start.sh for DataHub is not implemented yet."
-exec /bin/sh -c "echo 'Replace start.sh with application startup logic for DataHub' && sleep infinity"
+exit 1

apps/datahub/test/smoke.sh

@@ -1,16 +1,14 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Basic container reachability check executed inside the packaging container.
+cloudron_app_origin=${CLOUDRON_APP_ORIGIN:-http://localhost}
-# Replace curl target with an endpoint exposed by the app once the package is functional.
-cloudron_app_url=${CLOUDRON_APP_ORIGIN:-"http://localhost"}
 
-http_code=$(curl -s -o /tmp/smoke.log -w "%{http_code}" "${cloudron_app_url}")
+http_code=$(curl --silent --show-error --output /tmp/smoke.log --write-out "%{http_code}" "${cloudron_app_origin}/")
 
 if [[ "${http_code}" != "200" ]]; then
-  echo "Unexpected HTTP status: ${http_code}" >&2
+  >&2 echo "Smoke test failed for DataHub: expected HTTP 200 from ${cloudron_app_origin}/, got ${http_code}"
-  cat /tmp/smoke.log >&2
+  >&2 cat /tmp/smoke.log
   exit 1
 fi
 
-echo "Smoke test passed"
+echo "Smoke test placeholder passed for DataHub"

apps/docassemble/CloudronManifest.json

@@ -12,9 +12,16 @@
   "version": "0.1.0",
   "tags": ["custom", "known-element"],
   "healthCheckPath": "/",
-  "memoryLimit": 536870912,
   "httpPort": 3000,
+  "memoryLimit": "512M",
   "addons": {
     "localstorage": {}
+  },
+  "optionalAddons": {
+    "postgresql": {},
+    "redis": {},
+    "mysql": {},
+    "mongodb": {},
+    "sendmail": {}
   }
 }

apps/docassemble/Dockerfile

@@ -1,21 +1,38 @@
-# syntax=docker/dockerfile:1
+# syntax=docker/dockerfile:1.6
-FROM cloudron/base:5.0.0
 
+ARG APP_VERSION=latest
+
+FROM cloudron/base:5.0.0 AS builder
+WORKDIR /build
+
+# -----------------------------------------------------------------------------
+# TODO: Fetch and build Docassemble
+# Example:
+# RUN git clone --depth 1 --branch "${APP_VERSION}" https://github.com/jhpyle/docassemble.git source \
+#     && cd source \
+#     && npm ci \
+#     && npm run build
+# -----------------------------------------------------------------------------
+
+FROM cloudron/base:5.0.0
 LABEL org.opencontainers.image.source="https://github.com/jhpyle/docassemble.git"
 LABEL org.opencontainers.image.description="Cloudron package for Docassemble"
 
-ARG APP_VERSION
+ENV APP_VERSION=${APP_VERSION}
-ENV APP_VERSION=${APP_VERSION:-latest}
+
+# -----------------------------------------------------------------------------
+# TODO: Copy build artefacts from the builder stage
+# COPY --from=builder /build/source/dist /app/code
+# -----------------------------------------------------------------------------
 
-# Copy application source into image at build time
-# Replace this with a multi-stage build if upstream provides Docker images.
 COPY ./app /app/code
-
-# Copy start script and make it executable
 COPY ./start.sh /app/pkg/start.sh
-RUN chmod +x /app/pkg/start.sh
+COPY ./test /app/pkg/test
+
+RUN chmod +x /app/pkg/start.sh /app/pkg/test/smoke.sh \
+    && mkdir -p /app/data \
+    && chown -R cloudron:cloudron /app
 
-# Cloudron expects all processes to run as cloudron user
 USER cloudron
 WORKDIR /app/code
 

apps/docassemble/README.md

@@ -2,19 +2,19 @@
 
 - **Upstream repository**: https://github.com/jhpyle/docassemble.git
 - **Implementation issue**: https://projects.knownelement.com/issues/277
-- **Status**: Draft scaffolding generated on $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+- **Generated**: 2025-10-02T17:19:00Z UTC
 
 ## Packaging Checklist
 
-1. Review upstream deployment requirements and map them to Cloudron services (database, cache, object storage, workers).
+1. Map upstream services (databases, caches, workers) to Cloudron addons; remove unused entries from `optionalAddons` and enable required ones under `addons`.
-2. Update `Dockerfile` with the correct build steps and runtime dependencies.
+2. Implement the multi-stage build in `Dockerfile` to fetch/compile the correct release of Docassemble.
-3. Implement `start.sh` to configure the app from Cloudron-provided environment variables and launch the primary process.
+3. Update `start.sh` to configure the app from Cloudron environment variables and launch the primary process.
-4. Edit `CloudronManifest.json` with accurate metadata, permissions, ports, addons, and health checks.
+4. Replace the placeholder health checks and smoke test with real coverage.
-5. Add integration and smoke tests under `test/` to validate the package.
+5. Complete `CloudronManifest.json` (tagline, description, versioning, resource limits, ingress, TCP ports, etc.).
-6. Document manual configuration steps, migration requirements, and known gaps in this README.
+6. Document manual configuration steps, migrations, and known gaps below.
 
 ## Notes
 
-- Replace the placeholder long-running process in `start.sh`.
+- Populate the `app/` directory with runtime overlays or artifacts generated during the build stage.
-- Populate the `app/` directory with the application build artefacts or git submodules.
+- Use the shared packaging container (`docker/packager`) for `cloudron build/install` to keep the host clean.
-- Use the shared packaging container (`docker/packager`) to run `cloudron build` and `cloudron install` so the host remains clean.
+- Record decisions and operational requirements under `docs/apps/docassemble/` as work progresses.

apps/docassemble/metadata.json

@@ -4,6 +4,6 @@
   "issue": "https://projects.knownelement.com/issues/277",
   "repo": "https://github.com/jhpyle/docassemble.git",
   "additionalRepos": [],
-  "created": "2025-10-02T16:46:49Z",
+  "created": "2025-10-02T17:19:00Z",
   "notes": "TODO: capture packaging notes"
 }

apps/docassemble/start.sh

@@ -1,8 +1,9 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Cloudron injects configuration via environment variables and files under /run
+# TODO: render configuration files from CLOUDRON_* environment variables
-# Use this script to render config files and launch the upstream service.
+# Example:
+#   envsubst < /app/pkg/config.tmpl > /run/config.yaml
 
-# TODO: Replace the command below with the correct process supervisor.
+>&2 echo "start.sh for Docassemble is not implemented yet."
-exec /bin/sh -c "echo 'Replace start.sh with application startup logic for Docassemble' && sleep infinity"
+exit 1

apps/docassemble/test/smoke.sh

@@ -1,16 +1,14 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Basic container reachability check executed inside the packaging container.
+cloudron_app_origin=${CLOUDRON_APP_ORIGIN:-http://localhost}
-# Replace curl target with an endpoint exposed by the app once the package is functional.
-cloudron_app_url=${CLOUDRON_APP_ORIGIN:-"http://localhost"}
 
-http_code=$(curl -s -o /tmp/smoke.log -w "%{http_code}" "${cloudron_app_url}")
+http_code=$(curl --silent --show-error --output /tmp/smoke.log --write-out "%{http_code}" "${cloudron_app_origin}/")
 
 if [[ "${http_code}" != "200" ]]; then
-  echo "Unexpected HTTP status: ${http_code}" >&2
+  >&2 echo "Smoke test failed for Docassemble: expected HTTP 200 from ${cloudron_app_origin}/, got ${http_code}"
-  cat /tmp/smoke.log >&2
+  >&2 cat /tmp/smoke.log
   exit 1
 fi
 
-echo "Smoke test passed"
+echo "Smoke test placeholder passed for Docassemble"

apps/docker-webhook/CloudronManifest.json

@@ -12,9 +12,16 @@
   "version": "0.1.0",
   "tags": ["custom", "known-element"],
   "healthCheckPath": "/",
-  "memoryLimit": 536870912,
   "httpPort": 3000,
+  "memoryLimit": "512M",
   "addons": {
     "localstorage": {}
+  },
+  "optionalAddons": {
+    "postgresql": {},
+    "redis": {},
+    "mysql": {},
+    "mongodb": {},
+    "sendmail": {}
   }
 }

apps/docker-webhook/Dockerfile

@@ -1,21 +1,38 @@
-# syntax=docker/dockerfile:1
+# syntax=docker/dockerfile:1.6
-FROM cloudron/base:5.0.0
 
+ARG APP_VERSION=latest
+
+FROM cloudron/base:5.0.0 AS builder
+WORKDIR /build
+
+# -----------------------------------------------------------------------------
+# TODO: Fetch and build docker-webhook
+# Example:
+# RUN git clone --depth 1 --branch "${APP_VERSION}" https://github.com/thecatlady/docker-webhook source \
+#     && cd source \
+#     && npm ci \
+#     && npm run build
+# -----------------------------------------------------------------------------
+
+FROM cloudron/base:5.0.0
 LABEL org.opencontainers.image.source="https://github.com/thecatlady/docker-webhook"
 LABEL org.opencontainers.image.description="Cloudron package for docker-webhook"
 
-ARG APP_VERSION
+ENV APP_VERSION=${APP_VERSION}
-ENV APP_VERSION=${APP_VERSION:-latest}
+
+# -----------------------------------------------------------------------------
+# TODO: Copy build artefacts from the builder stage
+# COPY --from=builder /build/source/dist /app/code
+# -----------------------------------------------------------------------------
 
-# Copy application source into image at build time
-# Replace this with a multi-stage build if upstream provides Docker images.
 COPY ./app /app/code
-
-# Copy start script and make it executable
 COPY ./start.sh /app/pkg/start.sh
-RUN chmod +x /app/pkg/start.sh
+COPY ./test /app/pkg/test
+
+RUN chmod +x /app/pkg/start.sh /app/pkg/test/smoke.sh \
+    && mkdir -p /app/data \
+    && chown -R cloudron:cloudron /app
 
-# Cloudron expects all processes to run as cloudron user
 USER cloudron
 WORKDIR /app/code
 

apps/docker-webhook/README.md

@@ -2,19 +2,19 @@
 
 - **Upstream repository**: https://github.com/thecatlady/docker-webhook
 - **Implementation issue**: https://projects.knownelement.com/issues/271
-- **Status**: Draft scaffolding generated on $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+- **Generated**: 2025-10-02T17:19:00Z UTC
 
 ## Packaging Checklist
 
-1. Review upstream deployment requirements and map them to Cloudron services (database, cache, object storage, workers).
+1. Map upstream services (databases, caches, workers) to Cloudron addons; remove unused entries from `optionalAddons` and enable required ones under `addons`.
-2. Update `Dockerfile` with the correct build steps and runtime dependencies.
+2. Implement the multi-stage build in `Dockerfile` to fetch/compile the correct release of docker-webhook.
-3. Implement `start.sh` to configure the app from Cloudron-provided environment variables and launch the primary process.
+3. Update `start.sh` to configure the app from Cloudron environment variables and launch the primary process.
-4. Edit `CloudronManifest.json` with accurate metadata, permissions, ports, addons, and health checks.
+4. Replace the placeholder health checks and smoke test with real coverage.
-5. Add integration and smoke tests under `test/` to validate the package.
+5. Complete `CloudronManifest.json` (tagline, description, versioning, resource limits, ingress, TCP ports, etc.).
-6. Document manual configuration steps, migration requirements, and known gaps in this README.
+6. Document manual configuration steps, migrations, and known gaps below.
 
 ## Notes
 
-- Replace the placeholder long-running process in `start.sh`.
+- Populate the `app/` directory with runtime overlays or artifacts generated during the build stage.
-- Populate the `app/` directory with the application build artefacts or git submodules.
+- Use the shared packaging container (`docker/packager`) for `cloudron build/install` to keep the host clean.
-- Use the shared packaging container (`docker/packager`) to run `cloudron build` and `cloudron install` so the host remains clean.
+- Record decisions and operational requirements under `docs/apps/docker-webhook/` as work progresses.

apps/docker-webhook/metadata.json

@@ -4,6 +4,6 @@
   "issue": "https://projects.knownelement.com/issues/271",
   "repo": "https://github.com/thecatlady/docker-webhook",
   "additionalRepos": [],
-  "created": "2025-10-02T16:46:49Z",
+  "created": "2025-10-02T17:19:00Z",
   "notes": "TODO: capture packaging notes"
 }

apps/docker-webhook/start.sh

@@ -1,8 +1,9 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Cloudron injects configuration via environment variables and files under /run
+# TODO: render configuration files from CLOUDRON_* environment variables
-# Use this script to render config files and launch the upstream service.
+# Example:
+#   envsubst < /app/pkg/config.tmpl > /run/config.yaml
 
-# TODO: Replace the command below with the correct process supervisor.
+>&2 echo "start.sh for docker-webhook is not implemented yet."
-exec /bin/sh -c "echo 'Replace start.sh with application startup logic for docker-webhook' && sleep infinity"
+exit 1

apps/docker-webhook/test/smoke.sh

@@ -1,16 +1,14 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Basic container reachability check executed inside the packaging container.
+cloudron_app_origin=${CLOUDRON_APP_ORIGIN:-http://localhost}
-# Replace curl target with an endpoint exposed by the app once the package is functional.
-cloudron_app_url=${CLOUDRON_APP_ORIGIN:-"http://localhost"}
 
-http_code=$(curl -s -o /tmp/smoke.log -w "%{http_code}" "${cloudron_app_url}")
+http_code=$(curl --silent --show-error --output /tmp/smoke.log --write-out "%{http_code}" "${cloudron_app_origin}/")
 
 if [[ "${http_code}" != "200" ]]; then
-  echo "Unexpected HTTP status: ${http_code}" >&2
+  >&2 echo "Smoke test failed for docker-webhook: expected HTTP 200 from ${cloudron_app_origin}/, got ${http_code}"
-  cat /tmp/smoke.log >&2
+  >&2 cat /tmp/smoke.log
   exit 1
 fi
 
-echo "Smoke test passed"
+echo "Smoke test placeholder passed for docker-webhook"

apps/drawio/CloudronManifest.json

@@ -12,9 +12,16 @@
   "version": "0.1.0",
   "tags": ["custom", "known-element"],
   "healthCheckPath": "/",
-  "memoryLimit": 536870912,
   "httpPort": 3000,
+  "memoryLimit": "512M",
   "addons": {
     "localstorage": {}
+  },
+  "optionalAddons": {
+    "postgresql": {},
+    "redis": {},
+    "mysql": {},
+    "mongodb": {},
+    "sendmail": {}
   }
 }

apps/drawio/Dockerfile

@@ -1,21 +1,38 @@
-# syntax=docker/dockerfile:1
+# syntax=docker/dockerfile:1.6
-FROM cloudron/base:5.0.0
 
+ARG APP_VERSION=latest
+
+FROM cloudron/base:5.0.0 AS builder
+WORKDIR /build
+
+# -----------------------------------------------------------------------------
+# TODO: Fetch and build draw.io
+# Example:
+# RUN git clone --depth 1 --branch "${APP_VERSION}" https://github.com/jgraph/docker-drawio source \
+#     && cd source \
+#     && npm ci \
+#     && npm run build
+# -----------------------------------------------------------------------------
+
+FROM cloudron/base:5.0.0
 LABEL org.opencontainers.image.source="https://github.com/jgraph/docker-drawio"
 LABEL org.opencontainers.image.description="Cloudron package for draw.io"
 
-ARG APP_VERSION
+ENV APP_VERSION=${APP_VERSION}
-ENV APP_VERSION=${APP_VERSION:-latest}
+
+# -----------------------------------------------------------------------------
+# TODO: Copy build artefacts from the builder stage
+# COPY --from=builder /build/source/dist /app/code
+# -----------------------------------------------------------------------------
 
-# Copy application source into image at build time
-# Replace this with a multi-stage build if upstream provides Docker images.
 COPY ./app /app/code
-
-# Copy start script and make it executable
 COPY ./start.sh /app/pkg/start.sh
-RUN chmod +x /app/pkg/start.sh
+COPY ./test /app/pkg/test
+
+RUN chmod +x /app/pkg/start.sh /app/pkg/test/smoke.sh \
+    && mkdir -p /app/data \
+    && chown -R cloudron:cloudron /app
 
-# Cloudron expects all processes to run as cloudron user
 USER cloudron
 WORKDIR /app/code
 

apps/drawio/README.md

@@ -2,19 +2,19 @@
 
 - **Upstream repository**: https://github.com/jgraph/docker-drawio
 - **Implementation issue**: https://projects.knownelement.com/issues/272
-- **Status**: Draft scaffolding generated on $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+- **Generated**: 2025-10-02T17:19:01Z UTC
 
 ## Packaging Checklist
 
-1. Review upstream deployment requirements and map them to Cloudron services (database, cache, object storage, workers).
+1. Map upstream services (databases, caches, workers) to Cloudron addons; remove unused entries from `optionalAddons` and enable required ones under `addons`.
-2. Update `Dockerfile` with the correct build steps and runtime dependencies.
+2. Implement the multi-stage build in `Dockerfile` to fetch/compile the correct release of draw.io.
-3. Implement `start.sh` to configure the app from Cloudron-provided environment variables and launch the primary process.
+3. Update `start.sh` to configure the app from Cloudron environment variables and launch the primary process.
-4. Edit `CloudronManifest.json` with accurate metadata, permissions, ports, addons, and health checks.
+4. Replace the placeholder health checks and smoke test with real coverage.
-5. Add integration and smoke tests under `test/` to validate the package.
+5. Complete `CloudronManifest.json` (tagline, description, versioning, resource limits, ingress, TCP ports, etc.).
-6. Document manual configuration steps, migration requirements, and known gaps in this README.
+6. Document manual configuration steps, migrations, and known gaps below.
 
 ## Notes
 
-- Replace the placeholder long-running process in `start.sh`.
+- Populate the `app/` directory with runtime overlays or artifacts generated during the build stage.
-- Populate the `app/` directory with the application build artefacts or git submodules.
+- Use the shared packaging container (`docker/packager`) for `cloudron build/install` to keep the host clean.
-- Use the shared packaging container (`docker/packager`) to run `cloudron build` and `cloudron install` so the host remains clean.
+- Record decisions and operational requirements under `docs/apps/drawio/` as work progresses.

apps/drawio/metadata.json

@@ -4,6 +4,6 @@
   "issue": "https://projects.knownelement.com/issues/272",
   "repo": "https://github.com/jgraph/docker-drawio",
   "additionalRepos": [],
-  "created": "2025-10-02T16:46:49Z",
+  "created": "2025-10-02T17:19:01Z",
   "notes": "TODO: capture packaging notes"
 }

apps/drawio/start.sh

@@ -1,8 +1,9 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Cloudron injects configuration via environment variables and files under /run
+# TODO: render configuration files from CLOUDRON_* environment variables
-# Use this script to render config files and launch the upstream service.
+# Example:
+#   envsubst < /app/pkg/config.tmpl > /run/config.yaml
 
-# TODO: Replace the command below with the correct process supervisor.
+>&2 echo "start.sh for draw.io is not implemented yet."
-exec /bin/sh -c "echo 'Replace start.sh with application startup logic for draw.io' && sleep infinity"
+exit 1

apps/drawio/test/smoke.sh

@@ -1,16 +1,14 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Basic container reachability check executed inside the packaging container.
+cloudron_app_origin=${CLOUDRON_APP_ORIGIN:-http://localhost}
-# Replace curl target with an endpoint exposed by the app once the package is functional.
-cloudron_app_url=${CLOUDRON_APP_ORIGIN:-"http://localhost"}
 
-http_code=$(curl -s -o /tmp/smoke.log -w "%{http_code}" "${cloudron_app_url}")
+http_code=$(curl --silent --show-error --output /tmp/smoke.log --write-out "%{http_code}" "${cloudron_app_origin}/")
 
 if [[ "${http_code}" != "200" ]]; then
-  echo "Unexpected HTTP status: ${http_code}" >&2
+  >&2 echo "Smoke test failed for draw.io: expected HTTP 200 from ${cloudron_app_origin}/, got ${http_code}"
-  cat /tmp/smoke.log >&2
+  >&2 cat /tmp/smoke.log
   exit 1
 fi
 
-echo "Smoke test passed"
+echo "Smoke test placeholder passed for draw.io"

apps/easy-gate/CloudronManifest.json

@@ -12,9 +12,16 @@
   "version": "0.1.0",
   "tags": ["custom", "known-element"],
   "healthCheckPath": "/",
-  "memoryLimit": 536870912,
   "httpPort": 3000,
+  "memoryLimit": "512M",
   "addons": {
     "localstorage": {}
+  },
+  "optionalAddons": {
+    "postgresql": {},
+    "redis": {},
+    "mysql": {},
+    "mongodb": {},
+    "sendmail": {}
   }
 }

apps/easy-gate/Dockerfile

@@ -1,21 +1,38 @@
-# syntax=docker/dockerfile:1
+# syntax=docker/dockerfile:1.6
-FROM cloudron/base:5.0.0
 
+ARG APP_VERSION=latest
+
+FROM cloudron/base:5.0.0 AS builder
+WORKDIR /build
+
+# -----------------------------------------------------------------------------
+# TODO: Fetch and build Easy Gate
+# Example:
+# RUN git clone --depth 1 --branch "${APP_VERSION}" https://github.com/wiredlush/easy-gate.git source \
+#     && cd source \
+#     && npm ci \
+#     && npm run build
+# -----------------------------------------------------------------------------
+
+FROM cloudron/base:5.0.0
 LABEL org.opencontainers.image.source="https://github.com/wiredlush/easy-gate.git"
 LABEL org.opencontainers.image.description="Cloudron package for Easy Gate"
 
-ARG APP_VERSION
+ENV APP_VERSION=${APP_VERSION}
-ENV APP_VERSION=${APP_VERSION:-latest}
+
+# -----------------------------------------------------------------------------
+# TODO: Copy build artefacts from the builder stage
+# COPY --from=builder /build/source/dist /app/code
+# -----------------------------------------------------------------------------
 
-# Copy application source into image at build time
-# Replace this with a multi-stage build if upstream provides Docker images.
 COPY ./app /app/code
-
-# Copy start script and make it executable
 COPY ./start.sh /app/pkg/start.sh
-RUN chmod +x /app/pkg/start.sh
+COPY ./test /app/pkg/test
+
+RUN chmod +x /app/pkg/start.sh /app/pkg/test/smoke.sh \
+    && mkdir -p /app/data \
+    && chown -R cloudron:cloudron /app
 
-# Cloudron expects all processes to run as cloudron user
 USER cloudron
 WORKDIR /app/code
 

apps/easy-gate/README.md

@@ -2,19 +2,19 @@
 
 - **Upstream repository**: https://github.com/wiredlush/easy-gate.git
 - **Implementation issue**: https://projects.knownelement.com/issues/54
-- **Status**: Draft scaffolding generated on $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+- **Generated**: 2025-10-02T17:19:00Z UTC
 
 ## Packaging Checklist
 
-1. Review upstream deployment requirements and map them to Cloudron services (database, cache, object storage, workers).
+1. Map upstream services (databases, caches, workers) to Cloudron addons; remove unused entries from `optionalAddons` and enable required ones under `addons`.
-2. Update `Dockerfile` with the correct build steps and runtime dependencies.
+2. Implement the multi-stage build in `Dockerfile` to fetch/compile the correct release of Easy Gate.
-3. Implement `start.sh` to configure the app from Cloudron-provided environment variables and launch the primary process.
+3. Update `start.sh` to configure the app from Cloudron environment variables and launch the primary process.
-4. Edit `CloudronManifest.json` with accurate metadata, permissions, ports, addons, and health checks.
+4. Replace the placeholder health checks and smoke test with real coverage.
-5. Add integration and smoke tests under `test/` to validate the package.
+5. Complete `CloudronManifest.json` (tagline, description, versioning, resource limits, ingress, TCP ports, etc.).
-6. Document manual configuration steps, migration requirements, and known gaps in this README.
+6. Document manual configuration steps, migrations, and known gaps below.
 
 ## Notes
 
-- Replace the placeholder long-running process in `start.sh`.
+- Populate the `app/` directory with runtime overlays or artifacts generated during the build stage.
-- Populate the `app/` directory with the application build artefacts or git submodules.
+- Use the shared packaging container (`docker/packager`) for `cloudron build/install` to keep the host clean.
-- Use the shared packaging container (`docker/packager`) to run `cloudron build` and `cloudron install` so the host remains clean.
+- Record decisions and operational requirements under `docs/apps/easy-gate/` as work progresses.

apps/easy-gate/metadata.json

@@ -4,6 +4,6 @@
   "issue": "https://projects.knownelement.com/issues/54",
   "repo": "https://github.com/wiredlush/easy-gate.git",
   "additionalRepos": [],
-  "created": "2025-10-02T16:46:49Z",
+  "created": "2025-10-02T17:19:00Z",
   "notes": "TODO: capture packaging notes"
 }

apps/easy-gate/start.sh

@@ -1,8 +1,9 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Cloudron injects configuration via environment variables and files under /run
+# TODO: render configuration files from CLOUDRON_* environment variables
-# Use this script to render config files and launch the upstream service.
+# Example:
+#   envsubst < /app/pkg/config.tmpl > /run/config.yaml
 
-# TODO: Replace the command below with the correct process supervisor.
+>&2 echo "start.sh for Easy Gate is not implemented yet."
-exec /bin/sh -c "echo 'Replace start.sh with application startup logic for Easy Gate' && sleep infinity"
+exit 1

apps/easy-gate/test/smoke.sh

@@ -1,16 +1,14 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Basic container reachability check executed inside the packaging container.
+cloudron_app_origin=${CLOUDRON_APP_ORIGIN:-http://localhost}
-# Replace curl target with an endpoint exposed by the app once the package is functional.
-cloudron_app_url=${CLOUDRON_APP_ORIGIN:-"http://localhost"}
 
-http_code=$(curl -s -o /tmp/smoke.log -w "%{http_code}" "${cloudron_app_url}")
+http_code=$(curl --silent --show-error --output /tmp/smoke.log --write-out "%{http_code}" "${cloudron_app_origin}/")
 
 if [[ "${http_code}" != "200" ]]; then
-  echo "Unexpected HTTP status: ${http_code}" >&2
+  >&2 echo "Smoke test failed for Easy Gate: expected HTTP 200 from ${cloudron_app_origin}/, got ${http_code}"
-  cat /tmp/smoke.log >&2
+  >&2 cat /tmp/smoke.log
   exit 1
 fi
 
-echo "Smoke test passed"
+echo "Smoke test placeholder passed for Easy Gate"

apps/elabftw/CloudronManifest.json

@@ -12,9 +12,16 @@
   "version": "0.1.0",
   "tags": ["custom", "known-element"],
   "healthCheckPath": "/",
-  "memoryLimit": 536870912,
   "httpPort": 3000,
+  "memoryLimit": "512M",
   "addons": {
     "localstorage": {}
+  },
+  "optionalAddons": {
+    "postgresql": {},
+    "redis": {},
+    "mysql": {},
+    "mongodb": {},
+    "sendmail": {}
   }
 }

apps/elabftw/Dockerfile

@@ -1,21 +1,38 @@
-# syntax=docker/dockerfile:1
+# syntax=docker/dockerfile:1.6
-FROM cloudron/base:5.0.0
 
+ARG APP_VERSION=latest
+
+FROM cloudron/base:5.0.0 AS builder
+WORKDIR /build
+
+# -----------------------------------------------------------------------------
+# TODO: Fetch and build eLabFTW
+# Example:
+# RUN git clone --depth 1 --branch "${APP_VERSION}" https://github.com/elabftw/elabftw.git source \
+#     && cd source \
+#     && npm ci \
+#     && npm run build
+# -----------------------------------------------------------------------------
+
+FROM cloudron/base:5.0.0
 LABEL org.opencontainers.image.source="https://github.com/elabftw/elabftw.git"
 LABEL org.opencontainers.image.description="Cloudron package for eLabFTW"
 
-ARG APP_VERSION
+ENV APP_VERSION=${APP_VERSION}
-ENV APP_VERSION=${APP_VERSION:-latest}
+
+# -----------------------------------------------------------------------------
+# TODO: Copy build artefacts from the builder stage
+# COPY --from=builder /build/source/dist /app/code
+# -----------------------------------------------------------------------------
 
-# Copy application source into image at build time
-# Replace this with a multi-stage build if upstream provides Docker images.
 COPY ./app /app/code
-
-# Copy start script and make it executable
 COPY ./start.sh /app/pkg/start.sh
-RUN chmod +x /app/pkg/start.sh
+COPY ./test /app/pkg/test
+
+RUN chmod +x /app/pkg/start.sh /app/pkg/test/smoke.sh \
+    && mkdir -p /app/data \
+    && chown -R cloudron:cloudron /app
 
-# Cloudron expects all processes to run as cloudron user
 USER cloudron
 WORKDIR /app/code
 

apps/elabftw/README.md

@@ -2,19 +2,19 @@
 
 - **Upstream repository**: https://github.com/elabftw/elabftw.git
 - **Implementation issue**: https://projects.knownelement.com/issues/188
-- **Status**: Draft scaffolding generated on $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+- **Generated**: 2025-10-02T17:19:00Z UTC
 
 ## Packaging Checklist
 
-1. Review upstream deployment requirements and map them to Cloudron services (database, cache, object storage, workers).
+1. Map upstream services (databases, caches, workers) to Cloudron addons; remove unused entries from `optionalAddons` and enable required ones under `addons`.
-2. Update `Dockerfile` with the correct build steps and runtime dependencies.
+2. Implement the multi-stage build in `Dockerfile` to fetch/compile the correct release of eLabFTW.
-3. Implement `start.sh` to configure the app from Cloudron-provided environment variables and launch the primary process.
+3. Update `start.sh` to configure the app from Cloudron environment variables and launch the primary process.
-4. Edit `CloudronManifest.json` with accurate metadata, permissions, ports, addons, and health checks.
+4. Replace the placeholder health checks and smoke test with real coverage.
-5. Add integration and smoke tests under `test/` to validate the package.
+5. Complete `CloudronManifest.json` (tagline, description, versioning, resource limits, ingress, TCP ports, etc.).
-6. Document manual configuration steps, migration requirements, and known gaps in this README.
+6. Document manual configuration steps, migrations, and known gaps below.
 
 ## Notes
 
-- Replace the placeholder long-running process in `start.sh`.
+- Populate the `app/` directory with runtime overlays or artifacts generated during the build stage.
-- Populate the `app/` directory with the application build artefacts or git submodules.
+- Use the shared packaging container (`docker/packager`) for `cloudron build/install` to keep the host clean.
-- Use the shared packaging container (`docker/packager`) to run `cloudron build` and `cloudron install` so the host remains clean.
+- Record decisions and operational requirements under `docs/apps/elabftw/` as work progresses.

apps/elabftw/metadata.json

@@ -4,6 +4,6 @@
   "issue": "https://projects.knownelement.com/issues/188",
   "repo": "https://github.com/elabftw/elabftw.git",
   "additionalRepos": [],
-  "created": "2025-10-02T16:46:49Z",
+  "created": "2025-10-02T17:19:00Z",
   "notes": "TODO: capture packaging notes"
 }

apps/elabftw/start.sh

@@ -1,8 +1,9 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Cloudron injects configuration via environment variables and files under /run
+# TODO: render configuration files from CLOUDRON_* environment variables
-# Use this script to render config files and launch the upstream service.
+# Example:
+#   envsubst < /app/pkg/config.tmpl > /run/config.yaml
 
-# TODO: Replace the command below with the correct process supervisor.
+>&2 echo "start.sh for eLabFTW is not implemented yet."
-exec /bin/sh -c "echo 'Replace start.sh with application startup logic for eLabFTW' && sleep infinity"
+exit 1

apps/elabftw/test/smoke.sh

@@ -1,16 +1,14 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Basic container reachability check executed inside the packaging container.
+cloudron_app_origin=${CLOUDRON_APP_ORIGIN:-http://localhost}
-# Replace curl target with an endpoint exposed by the app once the package is functional.
-cloudron_app_url=${CLOUDRON_APP_ORIGIN:-"http://localhost"}
 
-http_code=$(curl -s -o /tmp/smoke.log -w "%{http_code}" "${cloudron_app_url}")
+http_code=$(curl --silent --show-error --output /tmp/smoke.log --write-out "%{http_code}" "${cloudron_app_origin}/")
 
 if [[ "${http_code}" != "200" ]]; then
-  echo "Unexpected HTTP status: ${http_code}" >&2
+  >&2 echo "Smoke test failed for eLabFTW: expected HTTP 200 from ${cloudron_app_origin}/, got ${http_code}"
-  cat /tmp/smoke.log >&2
+  >&2 cat /tmp/smoke.log
   exit 1
 fi
 
-echo "Smoke test passed"
+echo "Smoke test placeholder passed for eLabFTW"

apps/fleetdm-fleet/CloudronManifest.json

@@ -12,9 +12,16 @@
   "version": "0.1.0",
   "tags": ["custom", "known-element"],
   "healthCheckPath": "/",
-  "memoryLimit": 536870912,
   "httpPort": 3000,
+  "memoryLimit": "512M",
   "addons": {
     "localstorage": {}
+  },
+  "optionalAddons": {
+    "postgresql": {},
+    "redis": {},
+    "mysql": {},
+    "mongodb": {},
+    "sendmail": {}
   }
 }

apps/fleetdm-fleet/Dockerfile

@@ -1,21 +1,38 @@
-# syntax=docker/dockerfile:1
+# syntax=docker/dockerfile:1.6
-FROM cloudron/base:5.0.0
 
+ARG APP_VERSION=latest
+
+FROM cloudron/base:5.0.0 AS builder
+WORKDIR /build
+
+# -----------------------------------------------------------------------------
+# TODO: Fetch and build FleetDM Fleet
+# Example:
+# RUN git clone --depth 1 --branch "${APP_VERSION}" https://github.com/fleetdm/fleet.git source \
+#     && cd source \
+#     && npm ci \
+#     && npm run build
+# -----------------------------------------------------------------------------
+
+FROM cloudron/base:5.0.0
 LABEL org.opencontainers.image.source="https://github.com/fleetdm/fleet.git"
 LABEL org.opencontainers.image.description="Cloudron package for FleetDM Fleet"
 
-ARG APP_VERSION
+ENV APP_VERSION=${APP_VERSION}
-ENV APP_VERSION=${APP_VERSION:-latest}
+
+# -----------------------------------------------------------------------------
+# TODO: Copy build artefacts from the builder stage
+# COPY --from=builder /build/source/dist /app/code
+# -----------------------------------------------------------------------------
 
-# Copy application source into image at build time
-# Replace this with a multi-stage build if upstream provides Docker images.
 COPY ./app /app/code
-
-# Copy start script and make it executable
 COPY ./start.sh /app/pkg/start.sh
-RUN chmod +x /app/pkg/start.sh
+COPY ./test /app/pkg/test
+
+RUN chmod +x /app/pkg/start.sh /app/pkg/test/smoke.sh \
+    && mkdir -p /app/data \
+    && chown -R cloudron:cloudron /app
 
-# Cloudron expects all processes to run as cloudron user
 USER cloudron
 WORKDIR /app/code
 

apps/fleetdm-fleet/README.md

@@ -2,19 +2,19 @@
 
 - **Upstream repository**: https://github.com/fleetdm/fleet.git
 - **Implementation issue**: https://projects.knownelement.com/issues/195
-- **Status**: Draft scaffolding generated on $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+- **Generated**: 2025-10-02T17:19:00Z UTC
 
 ## Packaging Checklist
 
-1. Review upstream deployment requirements and map them to Cloudron services (database, cache, object storage, workers).
+1. Map upstream services (databases, caches, workers) to Cloudron addons; remove unused entries from `optionalAddons` and enable required ones under `addons`.
-2. Update `Dockerfile` with the correct build steps and runtime dependencies.
+2. Implement the multi-stage build in `Dockerfile` to fetch/compile the correct release of FleetDM Fleet.
-3. Implement `start.sh` to configure the app from Cloudron-provided environment variables and launch the primary process.
+3. Update `start.sh` to configure the app from Cloudron environment variables and launch the primary process.
-4. Edit `CloudronManifest.json` with accurate metadata, permissions, ports, addons, and health checks.
+4. Replace the placeholder health checks and smoke test with real coverage.
-5. Add integration and smoke tests under `test/` to validate the package.
+5. Complete `CloudronManifest.json` (tagline, description, versioning, resource limits, ingress, TCP ports, etc.).
-6. Document manual configuration steps, migration requirements, and known gaps in this README.
+6. Document manual configuration steps, migrations, and known gaps below.
 
 ## Notes
 
-- Replace the placeholder long-running process in `start.sh`.
+- Populate the `app/` directory with runtime overlays or artifacts generated during the build stage.
-- Populate the `app/` directory with the application build artefacts or git submodules.
+- Use the shared packaging container (`docker/packager`) for `cloudron build/install` to keep the host clean.
-- Use the shared packaging container (`docker/packager`) to run `cloudron build` and `cloudron install` so the host remains clean.
+- Record decisions and operational requirements under `docs/apps/fleetdm-fleet/` as work progresses.

apps/fleetdm-fleet/metadata.json

@@ -4,6 +4,6 @@
   "issue": "https://projects.knownelement.com/issues/195",
   "repo": "https://github.com/fleetdm/fleet.git",
   "additionalRepos": [],
-  "created": "2025-10-02T16:46:49Z",
+  "created": "2025-10-02T17:19:00Z",
   "notes": "TODO: capture packaging notes"
 }

apps/fleetdm-fleet/start.sh

@@ -1,8 +1,9 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Cloudron injects configuration via environment variables and files under /run
+# TODO: render configuration files from CLOUDRON_* environment variables
-# Use this script to render config files and launch the upstream service.
+# Example:
+#   envsubst < /app/pkg/config.tmpl > /run/config.yaml
 
-# TODO: Replace the command below with the correct process supervisor.
+>&2 echo "start.sh for FleetDM Fleet is not implemented yet."
-exec /bin/sh -c "echo 'Replace start.sh with application startup logic for FleetDM Fleet' && sleep infinity"
+exit 1

apps/fleetdm-fleet/test/smoke.sh

@@ -1,16 +1,14 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Basic container reachability check executed inside the packaging container.
+cloudron_app_origin=${CLOUDRON_APP_ORIGIN:-http://localhost}
-# Replace curl target with an endpoint exposed by the app once the package is functional.
-cloudron_app_url=${CLOUDRON_APP_ORIGIN:-"http://localhost"}
 
-http_code=$(curl -s -o /tmp/smoke.log -w "%{http_code}" "${cloudron_app_url}")
+http_code=$(curl --silent --show-error --output /tmp/smoke.log --write-out "%{http_code}" "${cloudron_app_origin}/")
 
 if [[ "${http_code}" != "200" ]]; then
-  echo "Unexpected HTTP status: ${http_code}" >&2
+  >&2 echo "Smoke test failed for FleetDM Fleet: expected HTTP 200 from ${cloudron_app_origin}/, got ${http_code}"
-  cat /tmp/smoke.log >&2
+  >&2 cat /tmp/smoke.log
   exit 1
 fi
 
-echo "Smoke test passed"
+echo "Smoke test placeholder passed for FleetDM Fleet"

apps/fonoster/CloudronManifest.json

@@ -12,9 +12,16 @@
   "version": "0.1.0",
   "tags": ["custom", "known-element"],
   "healthCheckPath": "/",
-  "memoryLimit": 536870912,
   "httpPort": 3000,
+  "memoryLimit": "512M",
   "addons": {
     "localstorage": {}
+  },
+  "optionalAddons": {
+    "postgresql": {},
+    "redis": {},
+    "mysql": {},
+    "mongodb": {},
+    "sendmail": {}
   }
 }

apps/fonoster/Dockerfile

@@ -1,21 +1,38 @@
-# syntax=docker/dockerfile:1
+# syntax=docker/dockerfile:1.6
-FROM cloudron/base:5.0.0
 
+ARG APP_VERSION=latest
+
+FROM cloudron/base:5.0.0 AS builder
+WORKDIR /build
+
+# -----------------------------------------------------------------------------
+# TODO: Fetch and build Fonoster
+# Example:
+# RUN git clone --depth 1 --branch "${APP_VERSION}" https://github.com/fonoster/fonoster.git source \
+#     && cd source \
+#     && npm ci \
+#     && npm run build
+# -----------------------------------------------------------------------------
+
+FROM cloudron/base:5.0.0
 LABEL org.opencontainers.image.source="https://github.com/fonoster/fonoster.git"
 LABEL org.opencontainers.image.description="Cloudron package for Fonoster"
 
-ARG APP_VERSION
+ENV APP_VERSION=${APP_VERSION}
-ENV APP_VERSION=${APP_VERSION:-latest}
+
+# -----------------------------------------------------------------------------
+# TODO: Copy build artefacts from the builder stage
+# COPY --from=builder /build/source/dist /app/code
+# -----------------------------------------------------------------------------
 
-# Copy application source into image at build time
-# Replace this with a multi-stage build if upstream provides Docker images.
 COPY ./app /app/code
-
-# Copy start script and make it executable
 COPY ./start.sh /app/pkg/start.sh
-RUN chmod +x /app/pkg/start.sh
+COPY ./test /app/pkg/test
+
+RUN chmod +x /app/pkg/start.sh /app/pkg/test/smoke.sh \
+    && mkdir -p /app/data \
+    && chown -R cloudron:cloudron /app
 
-# Cloudron expects all processes to run as cloudron user
 USER cloudron
 WORKDIR /app/code
 

apps/fonoster/README.md

@@ -2,19 +2,19 @@
 
 - **Upstream repository**: https://github.com/fonoster/fonoster.git
 - **Implementation issue**: https://projects.knownelement.com/issues/227
-- **Status**: Draft scaffolding generated on $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+- **Generated**: 2025-10-02T17:19:00Z UTC
 
 ## Packaging Checklist
 
-1. Review upstream deployment requirements and map them to Cloudron services (database, cache, object storage, workers).
+1. Map upstream services (databases, caches, workers) to Cloudron addons; remove unused entries from `optionalAddons` and enable required ones under `addons`.
-2. Update `Dockerfile` with the correct build steps and runtime dependencies.
+2. Implement the multi-stage build in `Dockerfile` to fetch/compile the correct release of Fonoster.
-3. Implement `start.sh` to configure the app from Cloudron-provided environment variables and launch the primary process.
+3. Update `start.sh` to configure the app from Cloudron environment variables and launch the primary process.
-4. Edit `CloudronManifest.json` with accurate metadata, permissions, ports, addons, and health checks.
+4. Replace the placeholder health checks and smoke test with real coverage.
-5. Add integration and smoke tests under `test/` to validate the package.
+5. Complete `CloudronManifest.json` (tagline, description, versioning, resource limits, ingress, TCP ports, etc.).
-6. Document manual configuration steps, migration requirements, and known gaps in this README.
+6. Document manual configuration steps, migrations, and known gaps below.
 
 ## Notes
 
-- Replace the placeholder long-running process in `start.sh`.
+- Populate the `app/` directory with runtime overlays or artifacts generated during the build stage.
-- Populate the `app/` directory with the application build artefacts or git submodules.
+- Use the shared packaging container (`docker/packager`) for `cloudron build/install` to keep the host clean.
-- Use the shared packaging container (`docker/packager`) to run `cloudron build` and `cloudron install` so the host remains clean.
+- Record decisions and operational requirements under `docs/apps/fonoster/` as work progresses.

apps/fonoster/metadata.json

@@ -4,6 +4,6 @@
   "issue": "https://projects.knownelement.com/issues/227",
   "repo": "https://github.com/fonoster/fonoster.git",
   "additionalRepos": [],
-  "created": "2025-10-02T16:46:49Z",
+  "created": "2025-10-02T17:19:00Z",
   "notes": "TODO: capture packaging notes"
 }

apps/fonoster/start.sh

@@ -1,8 +1,9 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Cloudron injects configuration via environment variables and files under /run
+# TODO: render configuration files from CLOUDRON_* environment variables
-# Use this script to render config files and launch the upstream service.
+# Example:
+#   envsubst < /app/pkg/config.tmpl > /run/config.yaml
 
-# TODO: Replace the command below with the correct process supervisor.
+>&2 echo "start.sh for Fonoster is not implemented yet."
-exec /bin/sh -c "echo 'Replace start.sh with application startup logic for Fonoster' && sleep infinity"
+exit 1

apps/fonoster/test/smoke.sh

@@ -1,16 +1,14 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Basic container reachability check executed inside the packaging container.
+cloudron_app_origin=${CLOUDRON_APP_ORIGIN:-http://localhost}
-# Replace curl target with an endpoint exposed by the app once the package is functional.
-cloudron_app_url=${CLOUDRON_APP_ORIGIN:-"http://localhost"}
 
-http_code=$(curl -s -o /tmp/smoke.log -w "%{http_code}" "${cloudron_app_url}")
+http_code=$(curl --silent --show-error --output /tmp/smoke.log --write-out "%{http_code}" "${cloudron_app_origin}/")
 
 if [[ "${http_code}" != "200" ]]; then
-  echo "Unexpected HTTP status: ${http_code}" >&2
+  >&2 echo "Smoke test failed for Fonoster: expected HTTP 200 from ${cloudron_app_origin}/, got ${http_code}"
-  cat /tmp/smoke.log >&2
+  >&2 cat /tmp/smoke.log
   exit 1
 fi
 
-echo "Smoke test passed"
+echo "Smoke test placeholder passed for Fonoster"

apps/grist/CloudronManifest.json

@@ -12,9 +12,16 @@
   "version": "0.1.0",
   "tags": ["custom", "known-element"],
   "healthCheckPath": "/",
-  "memoryLimit": 536870912,
   "httpPort": 3000,
+  "memoryLimit": "512M",
   "addons": {
     "localstorage": {}
+  },
+  "optionalAddons": {
+    "postgresql": {},
+    "redis": {},
+    "mysql": {},
+    "mongodb": {},
+    "sendmail": {}
   }
 }

apps/grist/Dockerfile

@@ -1,21 +1,38 @@
-# syntax=docker/dockerfile:1
+# syntax=docker/dockerfile:1.6
-FROM cloudron/base:5.0.0
 
+ARG APP_VERSION=latest
+
+FROM cloudron/base:5.0.0 AS builder
+WORKDIR /build
+
+# -----------------------------------------------------------------------------
+# TODO: Fetch and build Grist
+# Example:
+# RUN git clone --depth 1 --branch "${APP_VERSION}" https://github.com/gristlabs/grist-core source \
+#     && cd source \
+#     && npm ci \
+#     && npm run build
+# -----------------------------------------------------------------------------
+
+FROM cloudron/base:5.0.0
 LABEL org.opencontainers.image.source="https://github.com/gristlabs/grist-core"
 LABEL org.opencontainers.image.description="Cloudron package for Grist"
 
-ARG APP_VERSION
+ENV APP_VERSION=${APP_VERSION}
-ENV APP_VERSION=${APP_VERSION:-latest}
+
+# -----------------------------------------------------------------------------
+# TODO: Copy build artefacts from the builder stage
+# COPY --from=builder /build/source/dist /app/code
+# -----------------------------------------------------------------------------
 
-# Copy application source into image at build time
-# Replace this with a multi-stage build if upstream provides Docker images.
 COPY ./app /app/code
-
-# Copy start script and make it executable
 COPY ./start.sh /app/pkg/start.sh
-RUN chmod +x /app/pkg/start.sh
+COPY ./test /app/pkg/test
+
+RUN chmod +x /app/pkg/start.sh /app/pkg/test/smoke.sh \
+    && mkdir -p /app/data \
+    && chown -R cloudron:cloudron /app
 
-# Cloudron expects all processes to run as cloudron user
 USER cloudron
 WORKDIR /app/code
 

apps/grist/README.md

@@ -2,19 +2,19 @@
 
 - **Upstream repository**: https://github.com/gristlabs/grist-core
 - **Implementation issue**: https://projects.knownelement.com/issues/191
-- **Status**: Draft scaffolding generated on $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+- **Generated**: 2025-10-02T17:19:00Z UTC
 
 ## Packaging Checklist
 
-1. Review upstream deployment requirements and map them to Cloudron services (database, cache, object storage, workers).
+1. Map upstream services (databases, caches, workers) to Cloudron addons; remove unused entries from `optionalAddons` and enable required ones under `addons`.
-2. Update `Dockerfile` with the correct build steps and runtime dependencies.
+2. Implement the multi-stage build in `Dockerfile` to fetch/compile the correct release of Grist.
-3. Implement `start.sh` to configure the app from Cloudron-provided environment variables and launch the primary process.
+3. Update `start.sh` to configure the app from Cloudron environment variables and launch the primary process.
-4. Edit `CloudronManifest.json` with accurate metadata, permissions, ports, addons, and health checks.
+4. Replace the placeholder health checks and smoke test with real coverage.
-5. Add integration and smoke tests under `test/` to validate the package.
+5. Complete `CloudronManifest.json` (tagline, description, versioning, resource limits, ingress, TCP ports, etc.).
-6. Document manual configuration steps, migration requirements, and known gaps in this README.
+6. Document manual configuration steps, migrations, and known gaps below.
 
 ## Notes
 
-- Replace the placeholder long-running process in `start.sh`.
+- Populate the `app/` directory with runtime overlays or artifacts generated during the build stage.
-- Populate the `app/` directory with the application build artefacts or git submodules.
+- Use the shared packaging container (`docker/packager`) for `cloudron build/install` to keep the host clean.
-- Use the shared packaging container (`docker/packager`) to run `cloudron build` and `cloudron install` so the host remains clean.
+- Record decisions and operational requirements under `docs/apps/grist/` as work progresses.

apps/grist/metadata.json

@@ -4,6 +4,6 @@
   "issue": "https://projects.knownelement.com/issues/191",
   "repo": "https://github.com/gristlabs/grist-core",
   "additionalRepos": [],
-  "created": "2025-10-02T16:46:49Z",
+  "created": "2025-10-02T17:19:00Z",
   "notes": "TODO: capture packaging notes"
 }

apps/grist/start.sh

@@ -1,8 +1,9 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Cloudron injects configuration via environment variables and files under /run
+# TODO: render configuration files from CLOUDRON_* environment variables
-# Use this script to render config files and launch the upstream service.
+# Example:
+#   envsubst < /app/pkg/config.tmpl > /run/config.yaml
 
-# TODO: Replace the command below with the correct process supervisor.
+>&2 echo "start.sh for Grist is not implemented yet."
-exec /bin/sh -c "echo 'Replace start.sh with application startup logic for Grist' && sleep infinity"
+exit 1

apps/grist/test/smoke.sh

@@ -1,16 +1,14 @@
-#!/bin/bash
+#!/usr/bin/env bash
 set -euo pipefail
 
-# Basic container reachability check executed inside the packaging container.
+cloudron_app_origin=${CLOUDRON_APP_ORIGIN:-http://localhost}
-# Replace curl target with an endpoint exposed by the app once the package is functional.
-cloudron_app_url=${CLOUDRON_APP_ORIGIN:-"http://localhost"}
 
-http_code=$(curl -s -o /tmp/smoke.log -w "%{http_code}" "${cloudron_app_url}")
+http_code=$(curl --silent --show-error --output /tmp/smoke.log --write-out "%{http_code}" "${cloudron_app_origin}/")
 
 if [[ "${http_code}" != "200" ]]; then
-  echo "Unexpected HTTP status: ${http_code}" >&2
+  >&2 echo "Smoke test failed for Grist: expected HTTP 200 from ${cloudron_app_origin}/, got ${http_code}"
-  cat /tmp/smoke.log >&2
+  >&2 cat /tmp/smoke.log
   exit 1
 fi
 
-echo "Smoke test passed"
+echo "Smoke test placeholder passed for Grist"

apps/healthchecks/CloudronManifest.json

@@ -12,9 +12,16 @@
   "version": "0.1.0",
   "tags": ["custom", "known-element"],
   "healthCheckPath": "/",
-  "memoryLimit": 536870912,
   "httpPort": 3000,
+  "memoryLimit": "512M",
   "addons": {
     "localstorage": {}
+  },
+  "optionalAddons": {
+    "postgresql": {},
+    "redis": {},
+    "mysql": {},
+    "mongodb": {},
+    "sendmail": {}
   }
 }

apps/healthchecks/Dockerfile

@@ -1,21 +1,38 @@
-# syntax=docker/dockerfile:1
+# syntax=docker/dockerfile:1.6
-FROM cloudron/base:5.0.0
 
+ARG APP_VERSION=latest
+
+FROM cloudron/base:5.0.0 AS builder
+WORKDIR /build
+
+# -----------------------------------------------------------------------------
+# TODO: Fetch and build Healthchecks
+# Example:
+# RUN git clone --depth 1 --branch "${APP_VERSION}" https://github.com/healthchecks/healthchecks.git source \
+#     && cd source \
+#     && npm ci \
+#     && npm run build
+# -----------------------------------------------------------------------------
+
+FROM cloudron/base:5.0.0
 LABEL org.opencontainers.image.source="https://github.com/healthchecks/healthchecks.git"
 LABEL org.opencontainers.image.description="Cloudron package for Healthchecks"
 
-ARG APP_VERSION
+ENV APP_VERSION=${APP_VERSION}
-ENV APP_VERSION=${APP_VERSION:-latest}
+
+# -----------------------------------------------------------------------------
+# TODO: Copy build artefacts from the builder stage
+# COPY --from=builder /build/source/dist /app/code
+# -----------------------------------------------------------------------------
 
-# Copy application source into image at build time
-# Replace this with a multi-stage build if upstream provides Docker images.
 COPY ./app /app/code
-
-# Copy start script and make it executable
 COPY ./start.sh /app/pkg/start.sh
-RUN chmod +x /app/pkg/start.sh
+COPY ./test /app/pkg/test
+
+RUN chmod +x /app/pkg/start.sh /app/pkg/test/smoke.sh \
+    && mkdir -p /app/data \
+    && chown -R cloudron:cloudron /app
 
-# Cloudron expects all processes to run as cloudron user
 USER cloudron
 WORKDIR /app/code
 

apps/healthchecks/README.md

@@ -2,19 +2,19 @@
 
 - **Upstream repository**: https://github.com/healthchecks/healthchecks.git
 - **Implementation issue**: https://projects.knownelement.com/issues/192
-- **Status**: Draft scaffolding generated on $(date -u +"%Y-%m-%dT%H:%M:%SZ")
+- **Generated**: 2025-10-02T17:19:00Z UTC
 
 ## Packaging Checklist
 
-1. Review upstream deployment requirements and map them to Cloudron services (database, cache, object storage, workers).
+1. Map upstream services (databases, caches, workers) to Cloudron addons; remove unused entries from `optionalAddons` and enable required ones under `addons`.
-2. Update `Dockerfile` with the correct build steps and runtime dependencies.
+2. Implement the multi-stage build in `Dockerfile` to fetch/compile the correct release of Healthchecks.
-3. Implement `start.sh` to configure the app from Cloudron-provided environment variables and launch the primary process.
+3. Update `start.sh` to configure the app from Cloudron environment variables and launch the primary process.
-4. Edit `CloudronManifest.json` with accurate metadata, permissions, ports, addons, and health checks.
+4. Replace the placeholder health checks and smoke test with real coverage.
-5. Add integration and smoke tests under `test/` to validate the package.
+5. Complete `CloudronManifest.json` (tagline, description, versioning, resource limits, ingress, TCP ports, etc.).
-6. Document manual configuration steps, migration requirements, and known gaps in this README.
+6. Document manual configuration steps, migrations, and known gaps below.
 
 ## Notes
 
-- Replace the placeholder long-running process in `start.sh`.
+- Populate the `app/` directory with runtime overlays or artifacts generated during the build stage.
-- Populate the `app/` directory with the application build artefacts or git submodules.
+- Use the shared packaging container (`docker/packager`) for `cloudron build/install` to keep the host clean.
-- Use the shared packaging container (`docker/packager`) to run `cloudron build` and `cloudron install` so the host remains clean.
+- Record decisions and operational requirements under `docs/apps/healthchecks/` as work progresses.