consolidate: sync main with integration; add feature-only package files; archive feature docs under docs/feature-snapshots

CloudronPackages/APISIX/APISIX-BuildNotes.md

@@ -0,0 +1,62 @@
+# Apache APISIX Cloudron Package - Build Notes
+
+## Overview
+This document outlines the steps and considerations for packaging Apache APISIX for the Cloudron platform.
+
+## Package Components
+- `CloudronManifest.json`: Defines application metadata, addons (etcd), and environment variables.
+- `Dockerfile`: Builds the APISIX container image based on `apache/apisix:3.6.0-debian`.
+- `start.sh`: Script to dynamically configure APISIX and start the service.
+- `logo.png`: Application icon.
+
+## Configuration Details
+
+### Admin API Key
+The APISIX Admin API key is securely managed using Cloudron's secret mechanism. The `CLOUDRON_APP_SECRET` environment variable is used to inject a unique, strong key into APISIX's `config.yaml` at startup. This replaces the default `changeme` value.
+
+**To access the Admin API:**
+1.  Retrieve the `CLOUDRON_APP_SECRET` from your Cloudron instance's environment variables for the APISIX app.
+2.  Use this key in the `X-API-KEY` header when making requests to the APISIX Admin API (e.g., `http://your-domain/apisix/admin`).
+
+### Etcd Integration
+APISIX is configured to use Cloudron's managed etcd addon. The `start.sh` script dynamically sets the etcd host and port using `CLOUDRON_ETCD_HOST` and `CLOUDRON_ETCD_PORT` environment variables.
+
+### Health Check
+Cloudron's health check for the APISIX application is currently configured to probe the `/health` path. While APISIX primarily uses its Control API (`/v1/healthcheck`) for monitoring *upstream services*, `/health` is a common convention for application liveness probes. If issues arise with Cloudron's health monitoring, further investigation into a more specific APISIX health endpoint or a custom health check script may be required.
+
+## Local Testing
+
+**CRITICAL NOTE ON LOCAL TESTING**: 
+Despite configuring APISIX to connect to a custom etcd host via `config.yaml` and environment variables, the `apache/apisix:3.6.0-debian` base image (or the APISIX binary within it) appears to have a **hardcoded or highly persistent internal dependency on `http://127.0.0.1:2379` for etcd connectivity**. 
+
+Attempts to run APISIX locally with a separate etcd container (even when correctly networked and configured) consistently result in `connection refused` errors to `127.0.0.1:2379` and `all etcd nodes are unavailable` messages. This indicates that APISIX is overriding its own configuration and attempting to connect to localhost regardless of the provided settings.
+
+**Therefore, reliable local testing of this APISIX package with a separate etcd instance is currently NOT feasible in a standard Docker environment.** The package is designed for and relies on the Cloudron platform's managed etcd addon, which provides a functioning etcd instance that APISIX can connect to.
+
+To test the package locally (requires a running etcd instance accessible at `localhost:2379`):
+
+1.  **Build the Docker image**:
+    ```bash
+    docker build -t cloudron-apisix:latest CloudronPackages/APISIX/
+    ```
+2.  **Run the container (with mock etcd environment variables)**:
+    ```bash
+    docker run -it --rm -p 9080:9080 -p 9443:9443 \
+      -e CLOUDRON_ETCD_HOST=localhost -e CLOUDRON_ETCD_PORT=2379 \
+      -e CLOUDRON_APP_SECRET=your_test_admin_key \
+      cloudron-apisix:latest
+    ```
+    *Note: Replace `localhost` and `2379` with actual etcd host/port if running a local etcd instance. `your_test_admin_key` should be a temporary key for local testing.*
+
+3.  **Verify APISIX status (once running)**:
+    ```bash
+    curl -i http://localhost:9080/status
+    ```
+4.  **Test Admin API (replace with your test key)**:
+    ```bash
+    curl -i -X GET "http://localhost:9080/apisix/admin/routes" -H "X-API-KEY: your_test_admin_key"
+    ```
+
+## Known Issues / Limitations
+- Local standalone testing without a dedicated etcd instance is difficult due to APISIX's inherent design and apparent hardcoded etcd dependency.
+- The `/health` endpoint for Cloudron's health check might not be ideal for APISIX's internal state. Monitor closely.

CloudronPackages/APISIX/config.yaml

@@ -0,0 +1 @@
+# This is a placeholder config.yaml. It will be overwritten by start.sh

CloudronPackages/Jenkins/JenkinsBuildNotes.md

@@ -0,0 +1,99 @@
+# Jenkins for Cloudron - Build Notes
+
+This document provides instructions for building, testing, and deploying the Jenkins package to Cloudron.
+
+## Prerequisites
+
+- Cloudron server (version 5.4.0 or higher)
+- Docker installed on your build machine
+- Cloudron CLI tool installed (`npm install -g cloudron`)
+
+## File Structure
+
+```
+jenkins-cloudron/
+├── CloudronManifest.json     # Package definition
+├── Dockerfile                # Docker image build instructions
+├── start.sh                  # Initialization script
+├── nginx.conf                # NGINX configuration
+├── supervisor.conf           # Supervisor configuration for process management
+├── logo.png                  # App icon (128x128 PNG)
+├── casc_templates/           # Jenkins Configuration as Code templates
+│   ├── default.yaml          # Default authentication config
+│   ├── ldap.yaml             # LDAP authentication config
+│   └── oauth.yaml            # OAuth/OIDC authentication config
+```
+
+## Building the Package
+
+1. Create a directory for your package and place all files in the appropriate structure.
+
+2. Download a Jenkins logo (128x128 PNG) and save it as `logo.png`
+
+3. Build the Docker image:
+   ```bash
+   cloudron build
+   ```
+
+4. Test the package locally:
+   ```bash
+   cloudron install —image cloudron/jenkins
+   ```
+
+## Authentication Configuration
+
+The package supports three authentication methods:
+
+1. **Default (Local)**: Uses Jenkins’ built-in user database
+2. **LDAP**: Uses Cloudron’s LDAP server for authentication
+3. **OAuth/OIDC**: Uses Cloudron’s OAuth service for single sign-on
+
+The authentication method is automatically configured based on the presence of environment variables provided by Cloudron.
+
+## Testing
+
+After installation, test the following:
+
+1. **Basic functionality**:
+   - Access Jenkins through your Cloudron dashboard
+   - Verify the initial admin password works
+   - Create a simple pipeline job
+
+2. **Authentication**:
+   - Test LDAP integration by enabling the LDAP addon
+   - Test OAuth/OIDC integration by enabling the OAuth addon
+   - Verify user permissions are correctly applied
+
+3. **Persistence**:
+   - Install plugins through the Jenkins UI
+   - Restart the app to verify plugins persist
+   - Check that job configurations are maintained
+
+## Troubleshooting
+
+- **Jenkins doesn’t start**: Check logs using `cloudron logs -f`
+- **Authentication issues**: Verify the correct addons are enabled and configuration is applied
+- **Permission problems**: Check the ownership and permissions of files in `/app/data`
+
+## Updating Jenkins
+
+When a new version of Jenkins is released, update the Dockerfile to pull the latest version and rebuild the package.
+
+## Additional Notes
+
+- The package uses Jenkins Configuration as Code (JCasC) to automate the setup process
+- Jenkins runs as the `cloudron` user for proper permissions
+- Files in `/app/data/jenkins_home` are persisted across restarts and updates
+- Initial admin password is set to ‘adminpass’ for local authentication
+- **Java Version**: The package uses `openjdk-17-jdk`, which is a recommended Java version for Jenkins 2.516.1 LTS.
+- **Plugin Installation**: Plugins are now installed using `jenkins-plugin-cli` during the Docker build process, which handles dependencies automatically.
+
+## Deployment to Cloudron App Store
+
+If you wish to publish your app to the Cloudron App Store:
+
+1. Update the CloudronManifest.json with your details
+2. Test thoroughly on your own Cloudron instance
+3. Follow the Cloudron App Publishing guidelines
+
+Happy CI/CD with Jenkins on Cloudron!