# 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.