### Dockerfile Base Setup and APISIX Installation

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/05-build-process.md

Sets up the base image, installs APISIX from a package repository, and compiles the brotli module within a Dockerfile.

```dockerfile
FROM {base_image}

ARG APISIX_VERSION=3.17.0

# Install APISIX from package repository
RUN set -ex; \
    apt-get update && apt-get install -y apisix={APISIX_VERSION}-0

# Install optional modules
COPY ./install-brotli.sh /install-brotli.sh
RUN ./install-brotli.sh && rm /install-brotli.sh
```

--------------------------------

### Setup APISIX User and Permissions

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/05-build-process.md

Creates the 'apisix' system group and user, and sets ownership and permissions for the APISIX installation directory.

```bash
groupadd --system --gid 636 apisix
useradd --system --gid apisix --no-create-home --shell /usr/sbin/nologin --uid 636 apisix
chown -R apisix:0 /usr/local/apisix
chmod -R g=u /usr/local/apisix
```

--------------------------------

### Docker Compose APISIX Setup

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/12-quick-start-reference.md

Quickly start APISIX and its dependencies using Docker Compose. This method is suitable for multi-service environments.

```bash
# 1. Navigate to example directory
cd example

# 2. Start all services
docker-compose -f docker-compose.yml up -d

# 3. Verify services running
docker-compose ps

# 4. Test APISIX gateway
curl http://localhost:9080/

# 5. Check admin API (Admin key: edd1c9f034335f136f87ad84b625c8f1)
curl http://localhost:9180/apisix/admin/routes/ \
  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'

# 6. Access monitoring
# - Prometheus: http://localhost:9090
# - Grafana: http://localhost:3000 (admin/admin)

# 7. Stop all services
docker-compose down
```

--------------------------------

### Run APISIX with Custom Prefix

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/09-command-reference.md

Starts APISIX with a custom installation prefix and configuration directory mounted from the host. Ensures configurations are loaded from the specified custom path.

```bash
docker run -d --name apisix \
  -e APISIX_PREFIX=/opt/apisix \
  -v /custom/path:/opt/apisix/conf:ro \
  apache/apisix:3.17.0-debian
```

--------------------------------

### Start Docker Compose Services

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/09-command-reference.md

Starts all services defined in a Docker Compose configuration. Use specific compose files for different setups like standalone or default.

```bash
docker-compose up -d
```

```bash
docker-compose -f docker-compose.yml up -d
```

```bash
docker-compose -f docker-compose-standalone.yml up -d
```

--------------------------------

### Admin API Usage Example

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/03-configuration-reference.md

Example of how to authenticate and make a request to the APISIX Admin API using an API key.

```bash
curl http://localhost:9180/apisix/admin/services/ \
  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'
```

--------------------------------

### Example Docker Image Output

Source: https://github.com/apache/apisix-docker/blob/master/docs/en/latest/build.md

This is an example of the output you might see when running 'docker images' after a successful build, showing the repository, tag, image ID, creation time, and size.

```text
REPOSITORY        TAG            IMAGE ID       CREATED              SIZE
apache/apisix     3.5.0-debian   5c3b6ffdef06   About a minute ago   337MB
```

--------------------------------

### Plugin Configuration Schema and Example

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/10-types-and-schemas.md

Defines the structure for plugin configurations, including an identifier, description, plugins map, and timestamps. An example shows how to structure a plugin configuration.

```yaml
type PluginConfig {
  id: integer (required)             # Config identifier
  desc: string (optional)            # Description
  plugins: object (required)         # Plugins map
  created_at: integer (read-only)    # Timestamp
  updated_at: integer (read-only)    # Timestamp
}

# Example Plugin Config
plugin_config = {
  id: 1,
  desc: "Rate limiting and response rewriting",
  plugins: {
    rate-limit: {
      count: 100,
      time_window: 60
    },
    response-rewrite: {
      body: "Hello APISIX",
      headers: {
        "X-Custom-Header": "value"
      }
    }
  }
}
```

--------------------------------

### Start APISIX in Standalone Mode

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/02-docker-entry-points.md

Use this command to start APISIX in standalone mode. Initialization creates empty configuration files within the container.

```bash
docker run -d \
  --name apisix \
  -p 9080:9080 \
  -p 9443:9443 \
  -e APISIX_STAND_ALONE=true \
  apache/apisix:latest
```

--------------------------------

### Example Access Log Entry

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/07-monitoring-observability.md

An example of a standard Nginx access log entry, illustrating the format with specific request details.

```text
172.18.0.1 - - [24/Jun/2024 10:15:30 +0000] "GET /api/users HTTP/1.1" 200 1234 "-" "curl/7.81.0"
```

--------------------------------

### Install Brotli Module

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/05-build-process.md

Compiles and installs the brotli compression module for APISIX.

```bash
/install-brotli.sh  # Compile and install brotli module
```

--------------------------------

### Start Full Stack with Docker Compose

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/04-docker-compose-deployment.md

Starts all services defined in the docker-compose.yml file, including APISIX gateway, Admin API, etcd, Prometheus, Grafana, and upstream services. Use this to bring up the complete APISIX environment.

```bash
cd example
docker-compose -f docker-compose.yml up -d
```

--------------------------------

### Install APISIX Helm Chart

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/08-deployment-scenarios.md

Installs the APISIX Helm chart into a specified Kubernetes namespace. Ensure you have Helm installed and configured.

```bash
helm repo add apisix https://charts.apiseven.com
helm install apisix apisix/apisix \
  --namespace apisix-system \
  --create-namespace
```

--------------------------------

### All-in-One APISIX Container Startup Command

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/05-build-process.md

The command used to start APISIX and etcd within the all-in-one Docker image. It initializes etcd, APISIX, and then starts the APISIX server.

```bash
CMD ["sh", "-c", "(nohup etcd >/tmp/etcd.log 2>&1 &) && sleep 10 && /usr/bin/apisix init && /usr/bin/apisix init_etcd && /usr/local/openresty/bin/openresty -p /usr/local/apisix -g 'daemon off;'"]
```

--------------------------------

### Run APISIX with etcd (Solution 1)

Source: https://github.com/apache/apisix-docker/blob/master/README.md

Starts an APISIX container using the host network, configured to use etcd as its configuration center. Assumes etcd is already running.

```shell
docker run -d \
  --name apache-apisix \
  --net host \
  apache/apisix
```

--------------------------------

### etcd Admin Configuration Schema and Example

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/10-types-and-schemas.md

Defines the structure for etcd connection configurations, including hosts, prefix, timeout, and authentication details. An example demonstrates a typical etcd configuration.

```yaml
type EtcdConfig {
  host: array[string] (required)     # etcd endpoints: ["http://host:2379"]
  prefix: string (optional)          # Key prefix: "/apisix"
  timeout: integer (optional)        # Connection timeout: 30 seconds
  user: string (optional)            # etcd username (if auth enabled)
  password: string (optional)        # etcd password (if auth enabled)
  tls:
    cert: string (optional)          # Client certificate path
    key: string (optional)           # Client key path
    ca: string (optional)            # CA certificate path
}

# Example etcd Config
etcd_config = {
  host: [
    "http://etcd-1:2379",
    "http://etcd-2:2379",
    "http://etcd-3:2379"
  ],
  prefix: "/apisix",
  timeout: 30
}
```

--------------------------------

### List Routes API Response Example

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/06-api-admin-endpoints.md

Example JSON response when listing routes, showing total count and a list of route objects.

```json
{
  "total": 1,
  "list": [
    {
      "id": "1",
      "uri": "/api/v1/users",
      "methods": ["GET", "POST"],
      "upstream": {...},
      "created_at": 1234567890,
      "updated_at": 1234567890
    }
  ]
}
```

--------------------------------

### Run APISIX Standalone

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/09-command-reference.md

Starts a basic APISIX instance in standalone mode, listening on default ports. Ensures APISIX starts with empty routes and standalone mode enabled.

```bash
docker run -d --name apisix \
  -p 9080:9080 \
  -p 9443:9443 \
  -p 9180:9180 \
  -p 9091:9091 \
  -p 9092:9092 \
  -e APISIX_STAND_ALONE=true \
  apache/apisix:3.17.0-debian
```

--------------------------------

### Verify APISIX Installation (Debian/Ubuntu)

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/05-build-process.md

Verifies the installation of APISIX and its dependencies like OpenResty on Debian/Ubuntu systems.

```bash
openresty -V       # Check OpenResty version
apisix version      # Check APISIX version
```

--------------------------------

### Install APISIX Package (Debian/Ubuntu)

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/05-build-process.md

Updates package lists and installs the APISIX package from the configured repository on Debian/Ubuntu.

```bash
apt update
apt install -y apisix={APISIX_VERSION}-0
```

--------------------------------

### Standalone APISIX Setup

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/12-quick-start-reference.md

Set up APISIX in standalone mode using a configuration file and Docker. This is useful for quick testing and development.

```bash
# 1. Create apisix.yaml
mkdir -p ./apisix_conf
cat > ./apisix_conf/apisix.yaml << 'EOF'
routes:
  - id: test_route
    uri: /test
    upstream:
      nodes:
        "httpbin.org": 1
      type: roundrobin
#END
EOF

# 2. Run APISIX container
docker run -d --name apisix \
  -p 9080:9080 \
  -p 9180:9180 \
  -e APISIX_STAND_ALONE=true \
  -v $(pwd)/apisix_conf/apisix.yaml:/usr/local/apisix/conf/apisix.yaml:ro \
  apache/apisix:3.17.0-debian

# 3. Wait for startup (5 seconds)
sleep 5

# 4. Test the route
curl http://localhost:9080/test
```

--------------------------------

### Create Docker Network and Start etcd (Solution 2)

Source: https://github.com/apache/apisix-docker/blob/master/README.md

Creates a custom Docker bridge network named 'apisix-network' and starts an etcd container within it. This is the first step for Solution 2, using etcd with a dedicated network.

```shell
docker network create apisix-network --driver bridge && \
docker network inspect -v apisix-network && \
docker run -d --name etcd \
  --network apisix-network \
  -p 2379:2379 \
  -p 2380:2380 \
  -e ALLOW_NONE_AUTHENTICATION=yes \
  -e ETCD_ADVERTISE_CLIENT_URLS=http://127.0.0.1:2379 \
  bitnamilegacy/etcd:3.5.11
```

--------------------------------

### Create Consumer

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/06-api-admin-endpoints.md

Creates a new consumer with username, description, and plugin configurations. The 'key-auth' plugin example shows how to secure a consumer.

```http
POST /apisix/admin/consumers/
Content-Type: application/json

{
  "username": "user1",
  "desc": "API user",
  "plugins": {
    "key-auth": {
      "key": "secret-key-123"
    }
  }
}
```

--------------------------------

### Example Upstream Configuration

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/10-types-and-schemas.md

Illustrates a complete upstream configuration with round-robin balancing, specific node weights, and active HTTP health checks.

```yaml
upstream = {
  id: "api_backend",
  type: "roundrobin",
  nodes: {
    "api1.internal:8000": 1,
    "api2.internal:8000": 1,
    "api3.internal:8000": 2
  },
  timeout: {
    connect: 10,
    send: 30,
    read: 30
  },
  healthchecks: {
    active: {
      type: "http",
      http_path: "/health",
      healthy: {
        interval: 1,
        successes: 2
      },
      unhealthy: {
        interval: 1,
        http_failures: 5
      }
    }
  }
}
```

--------------------------------

### Plugin Configuration Example (Prometheus)

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/03-configuration-reference.md

Configure plugin-specific attributes, such as the export address and port for the Prometheus metrics endpoint.

```yaml
plugin_attr:
  prometheus:
    export_addr:
      ip: "0.0.0.0"
      port: 9091              # Metrics scrape port
```

--------------------------------

### 5-Minute Standalone APISIX Setup

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/README.md

This snippet demonstrates how to set up APISIX in standalone mode. It involves creating a configuration file and running the APISIX Docker container with specific volume mounts and environment variables. Use this for quick local testing.

```bash
# Create config
mkdir -p ./apisix_conf
cat > ./apisix_conf/apisix.yaml << 'EOF'
routes:
  - id: test
    uri: /test
    upstream:
      nodes:
        "httpbin.org": 1
      type: roundrobin
#END
EOF

# Run container
docker run -d --name apisix \
  -p 9080:9080 \
  -p 9180:9180 \
  -e APISIX_STAND_ALONE=true \
  -v $(pwd)/apisix_conf/apisix.yaml:/usr/local/apisix/conf/apisix.yaml:ro \
  apache/apisix:3.17.0-debian

# Test
sleep 5
curl http://localhost:9080/test
```

--------------------------------

### URI Pattern Matching Examples

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/10-types-and-schemas.md

Demonstrates various URI pattern matching syntaxes for routing. Includes exact matches, single and multiple segment wildcards, path parameters, and custom regex.

```yaml
type URIPattern = string

# Exact match
uri: "/api/users"                    # Matches only /api/users

# Wildcard single segment
uri: "/api/*/profile"                # Matches /api/user/profile, /api/admin/profile

# Wildcard multiple segments
uri: "/api/**"                       # Matches /api/users, /api/users/123, etc.

# Path parameter (not standard URI matching, requires route matching)
uri: "/api/users/:id"               # Syntax for documented route

# Regex (not standard APISIX)
uri: "/api/users/[0-9]+"            # Custom implementation
```

--------------------------------

### Docker Compose: Start APISIX Cluster

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/00-INDEX.md

Command to start an APISIX cluster defined in a docker-compose.yml file. This brings up all services, including APISIX and etcd.

```bash
docker-compose up -d

```

--------------------------------

### Plugin Configuration Example

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/03-configuration-reference.md

Defines a reusable plugin configuration with an ID and specific plugin settings, such as response rewriting.

```yaml
plugin_configs:
  - 
    id: 1
    plugins:
      response-rewrite:
        body: "Hello APISIX\n"
        headers:
          X-Custom: "value"
    desc: "response-rewrite"
```

--------------------------------

### Start OpenResty in Foreground

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/02-docker-entry-points.md

This command starts the OpenResty server in the foreground, which is required for Docker containers. It sets the prefix directory and specifies daemon off.

```bash
exec /usr/local/openresty/bin/openresty -p /usr/local/apisix -g 'daemon off;'
```

--------------------------------

### Dockerfile User and Environment Setup

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/05-build-process.md

Configures the APISIX user, sets the working directory, and defines environment variables for the PATH in a Dockerfile.

```dockerfile
# Setup permissions
RUN groupadd --system apisix && useradd --system apisix

WORKDIR /usr/local/apisix
ENV PATH=$PATH:/usr/local/openresty/luajit/bin:/usr/local/openresty/nginx/sbin:/usr/local/openresty/bin

USER apisix
```

--------------------------------

### Start etcd Container for APISIX

Source: https://github.com/apache/apisix-docker/blob/master/README.md

Starts an etcd container using the host network. Ensure ports 2379, 2380 are available. This is for Solution 1 of using etcd as a configuration center.

```shell
docker run -d \
  --name etcd \
  --net host \
  -e ALLOW_NONE_AUTHENTICATION=yes \
  -e ETCD_ADVERTISE_CLIENT_URLS=http://127.0.0.1:2379 \
  bitnamilegacy/etcd:3.5.11
```

--------------------------------

### Run APISIX with etcd

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/09-command-reference.md

Starts an APISIX instance configured to use an etcd backend. Requires a separate etcd container to be linked or networked.

```bash
docker run -d --name apisix \
  -p 9080:9080 \
  -p 9180:9180 \
  -p 9091:9091 \
  -v /path/to/config.yaml:/usr/local/apisix/conf/config.yaml:ro \
  --link etcd:etcd \
  apache/apisix:3.17.0-debian
```

--------------------------------

### Blue-Green Deployment Setup

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/08-deployment-scenarios.md

Defines two APISIX instances (blue and green) for a Blue-Green deployment strategy. Ensure separate ports are exposed for each instance.

```yaml
version: "3"
services:
  apisix-blue:
    image: apache/apisix:3.17.0-debian
    volumes:
      - ./apisix_conf/config.yaml:/usr/local/apisix/conf/config.yaml:ro
    ports:
      - "9080:9080"  # Main port
      - "9180:9180"
    environment:
      ENVIRONMENT: blue

  apisix-green:
    image: apache/apisix:3.17.0-debian
    volumes:
      - ./apisix_conf/config.yaml:/usr/local/apisix/conf/config.yaml:ro
    ports:
      - "9081:9080"  # Different port
      - "9181:9180"
    environment:
      ENVIRONMENT: green

  etcd:
    image: bitnamilegacy/etcd:3.5.11
    # Shared configuration store
```

--------------------------------

### IP Allow List Examples (CIDR Format)

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/10-types-and-schemas.md

Examples of using CIDR notation for IP allow lists. This format is used to specify IP address ranges for access control.

```yaml
type CIDR = string

# Examples
CIDR examples:
  "0.0.0.0/0"                  # All IPv4
  "192.168.1.0/24"             # Private network
  "10.0.0.0/8"                 # Class A private
  "172.16.0.0/12"              # Class B private
  "127.0.0.1/32"               # Localhost only
  "203.0.113.0/24"             # Specific /24 subnet
  "::/0"                        # All IPv6 (if enable_ipv6: true)
```

--------------------------------

### Start APISIX in etcd Mode

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/02-docker-entry-points.md

Run APISIX with etcd as the configuration backend. This requires specifying the etcd connection details in your configuration file and mounting it into the container.

```bash
docker run -d \
  --name apisix \
  -p 9080:9080 \
  -p 9180:9180 \
  -v /path/to/config.yaml:/usr/local/apisix/conf/config.yaml:ro \
  apache/apisix:latest
```

--------------------------------

### Get All APISIX Configuration

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/09-command-reference.md

Retrieves all configuration entries under the /apisix prefix in etcd.

```bash
docker-compose exec etcd etcdctl get /apisix --prefix
```

--------------------------------

### List APISIX Routes

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/09-command-reference.md

Retrieve a list of all configured routes in APISIX. Includes an example for pretty-printing the output using `jq`.

```bash
curl http://localhost:9180/apisix/admin/routes/ \
  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'

# Pretty print
curl http://localhost:9180/apisix/admin/routes/ \
  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' | jq
```

--------------------------------

### Timestamp Format Example

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/10-types-and-schemas.md

Illustrates the Unix epoch timestamp format for 'created_at' and 'updated_at' fields. Includes bash commands for converting timestamps.

```yaml
created_at: 1719222930              # Represents: 2024-06-24 10:15:30 UTC
updated_at: 1719222930

# Convert in bash
date -d @1719222930                 # Shows: 24 Jun 10:15:30
date +%s                            # Get current timestamp
```

--------------------------------

### Create Canary Release Routes

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/08-deployment-scenarios.md

Implement a canary release strategy by creating two routes for different backend versions. This example sets up a route for the old version receiving 90% of traffic and a new version receiving 10%.

```bash
# Old version route (90% traffic)
curl -X POST http://localhost:9180/apisix/admin/routes/ \
  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "api_v1_old",
    "uri": "/api/v1/*",
    "upstream": {
      "nodes": {"backend-v1:8000": 90}
    }
  }'

# New version route (10% traffic)
curl -X POST http://localhost:9180/apisix/admin/routes/ \
  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "api_v1_new",
    "uri": "/api/v1/*",
    "upstream": {
      "nodes": {"backend-v2:8000": 10}
    }
  }'
```

--------------------------------

### Run APISIX with etcd using Custom Config (Solution 2)

Source: https://github.com/apache/apisix-docker/blob/master/README.md

Starts an APISIX container on the 'apisix-network', mapping ports and mounting the custom config.yaml file that points to the etcd configuration center.

```shell
docker run -d --name apache-apisix \
  --network apisix-network \
  -p 9080:9080 \
  -p 9180:9180 \
  -v $(pwd)/config.yaml:/usr/local/apisix/conf/config.yaml \
  apache/apisix
```

--------------------------------

### Run APISIX with Config File Mounts

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/09-command-reference.md

Starts APISIX with custom configuration files mounted from the host. Supports read-only (`:ro`) or read-write mounts for dynamic updates.

```bash
docker run -d --name apisix \
  -p 9080:9080 \
  -p 9180:9180 \
  -v ./apisix.yaml:/usr/local/apisix/conf/apisix.yaml:ro \
  -v ./config.yaml:/usr/local/apisix/conf/config.yaml:ro \
  -e APISIX_STAND_ALONE=true \
  apache/apisix:3.17.0-debian
```

--------------------------------

### Performance Testing with wrk

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/00-INDEX.md

Example of using the 'wrk' tool to perform HTTP load testing against an APISIX endpoint. This helps in assessing performance under load.

```bash
wrk -t4 -c100 -d30s http://127.0.0.1:9080/test

```

--------------------------------

### Initialize APISIX etcd Schema

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/09-command-reference.md

Create the default etcd keys and configuration structure for APISIX. This is automatic when the container starts in etcd mode.

```bash
docker-compose exec apisix apisix init_etcd
```

--------------------------------

### Kubernetes Ingress Resource Example

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/08-deployment-scenarios.md

Defines a Kubernetes Ingress resource to route traffic for 'api.example.com/api' to a backend service. This configuration is read by the apisix-ingress-controller.

```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  name: example
spec:
  rules:
  - host: api.example.com
    http:
      paths:
      - path: /api
        pathType: Prefix
        backend:
          service:
            name: backend-service
            port:
              number: 8000
```

--------------------------------

### Add APISIX Repository (Debian/Ubuntu)

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/05-build-process.md

Adds the APISIX repository GPG key and source list for package installation on Debian/Ubuntu.

```bash
wget -O - https://repos.apiseven.com/pubkey.gpg | apt-key add -

```

```bash
echo "deb https://repos.apiseven.com/packages/debian debian12 main" | tee /etc/apt/sources.list.d/apisix.list
```

--------------------------------

### Run APISIX with Docker Compose

Source: https://github.com/apache/apisix-docker/blob/master/docs/en/latest/example.md

Starts APISIX and its dependencies in detached mode using Docker Compose.

```bash
docker-compose -d
```

--------------------------------

### Configure APISIX Services and Routes

Source: https://github.com/apache/apisix-docker/blob/master/docs/en/latest/example.md

Uses curl to configure two services and two routes for APISIX. Ensure the API key is correct for your setup.

```bash
curl http://127.0.0.1:9180/apisix/admin/services/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "web1:80": 1
        }
    }
}'
```

```bash
curl http://127.0.0.1:9180/apisix/admin/services/2 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "upstream": {
        "type": "roundrobin",
        "nodes": {
            "web2:80": 1
        }
    }
}'
```

```bash
curl http://127.0.0.1:9180/apisix/admin/routes/12 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "uri": "/*",
    "host": "web1.lvh.me",
    "service_id": "1"
}'
```

```bash
curl http://127.0.0.1:9180/apisix/admin/routes/22 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d '
{
    "uri": "/*",
    "host": "web2.lvh.me",
    "service_id": "2"
}'
```

```bash
curl http://127.0.0.1:9180/apisix/admin/ssl/1 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d "
{
    \"cert\": \"$( cat './mkcert/lvh.me+1.pem')\",
    \"key\": \"$( cat './mkcert/lvh.me+1-key.pem')\",
    \"sni\": \"lvh.me\" 
}"
```

```bash
curl http://127.0.0.1:9180/apisix/admin/ssl/2 -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' -X PUT -d "
{
    \"cert\": \"$( cat './mkcert/lvh.me+1.pem')\",
    \"key\": \"$( cat './mkcert/lvh.me+1-key.pem')\",
    \"sni\": \"*.lvh.me\" 
}"
```

--------------------------------

### Detect Architecture (Debian/Ubuntu)

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/05-build-process.md

Detects the system architecture for package installation on Debian/Ubuntu systems.

```bash
arch=$(dpkg --print-architecture)  # amd64 or arm64
```

--------------------------------

### Run Custom Commands via Fallback

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/02-docker-entry-points.md

Examples of using the fallback command execution to drop into a shell, run the APISIX CLI, or execute custom shell commands.

```bash
docker run apache/apisix bash          # Drop into shell
docker run apache/apisix apisix -h     # Run apisix CLI
docker run apache/apisix sh -c '...'   # Run custom commands
```

--------------------------------

### Standalone Docker Run for APISIX

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/00-INDEX.md

Example of running APISIX in standalone mode using Docker. This configuration does not rely on etcd for dynamic configuration.

```bash
docker run --rm -p 9080:80 apache/apisix:3.5.0

```

--------------------------------

### Testing a Complete APISIX Pipeline with Docker Compose

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/12-quick-start-reference.md

Steps to start the APISIX Docker Compose stack, create a test route, send a request, check metrics, and view results in Grafana.

```bash
# 1. Start full docker-compose stack
cd example
docker-compose up -d
```

```bash
# 2. Create a test route
curl -X POST http://localhost:9180/apisix/admin/routes/ \
  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1' \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "test",
    "uri": "/test",
    "upstream": {
      "nodes": {"web1": 1},
      "type": "roundrobin"
    }
  }'
```

```bash
# 3. Send request
curl http://localhost:9080/test
```

```bash
# 4. Check metrics
curl -s http://localhost:9091/apisix/prometheus/metrics | grep test
```

```bash
# 5. View in Grafana
# Open http://localhost:3000 (admin/admin)
```

--------------------------------

### Standalone APISIX Configuration with Routes and Plugin Configs

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/03-configuration-reference.md

This example demonstrates a standalone APISIX configuration that includes defining routes and configuring plugins. It shows how to set up a route with a URI, upstream, and a response-rewrite plugin, as well as global plugin configurations.

```yaml
routes:
  - id: httpbin
    uri: /*
    upstream:
      nodes:
        "httpbin.org": 1
      type: roundrobin
    plugins:
      response-rewrite:
        body: "Hello APISIX\n"

plugin_configs:
  - id: 1
    plugins:
      response-rewrite:
        body: "Hello World"
```

--------------------------------

### Route Definition Example

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/03-configuration-reference.md

Defines a route with a specific URI, HTTP methods, upstream configuration, and inline plugin settings. It also references a reusable plugin configuration by ID.

```yaml
routes:
  - 
    id: route_id_1                # Unique identifier
    uri: /api/v1/users           # Request URI pattern
    methods: ["GET", "POST"]      # HTTP methods
    upstream:
      type: roundrobin            # Load balancing algorithm
      nodes:
        "backend1:8080": 1        # target:port with weight
        "backend2:8080": 1
    plugins:
      rate-limit:
        count: 100
        time_window: 60
    plugin_config_id: 1           # Reference to plugin_configs
```

--------------------------------

### Run APISIX in Stand-alone Mode

Source: https://github.com/apache/apisix-docker/blob/master/README.md

Starts an APISIX container in stand-alone mode, using apisix.yaml for configuration. Ensure port 9080 is available.

```shell
docker run -d --name apache-apisix \
  -p 9080:9080 \
  -e APISIX_STAND_ALONE=true \
  apache/apisix
```

--------------------------------

### Create Plugin Config

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/06-api-admin-endpoints.md

Creates a reusable plugin configuration with a unique ID and plugin definitions. Example includes rate limiting and response rewriting.

```http
POST /apisix/admin/plugin_configs/
Content-Type: application/json

{
  "id": 1,
  "desc": "Rate limit config",
  "plugins": {
    "rate-limit": {
      "count": 100,
      "time_window": 60
    },
    "response-rewrite": {
      "body": "Modified response"
    }
  }
}
```

--------------------------------

### Configure APISIX Stand-alone with Routes and Plugins

Source: https://github.com/apache/apisix-docker/blob/master/README.md

Adds route and plugin configurations to a running APISIX container in stand-alone mode by piping the configuration to apisix.yaml. This example configures a basic route with a response-rewrite plugin.

```shell
docker exec -i apache-apisix sh -c 'cat > /usr/local/apisix/conf/apisix.yaml <<_EOC_\
routes: 
  - 
    id: httpbin
    uri: /*
    upstream: 
      nodes: 
        "httpbin.org": 1
      type: roundrobin
    plugin_config_id: 1

plugin_configs:
  - 
    id: 1
    plugins:
      response-rewrite: 
        body: "Hello APISIX\n"
    desc: "response-rewrite"
#END
_EOC_'
```

--------------------------------

### Display All Makefile Build Targets

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/05-build-process.md

Run the 'help' target in the Makefile to list all available build targets and their descriptions. This is useful for understanding the available build options.

```makefile
make help
```

--------------------------------

### Run APISIX Integration Tests with Docker Compose

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/11-troubleshooting-guide.md

Use Docker Compose to set up the full APISIX environment for integration testing. This includes starting services, verifying their status, and executing the test suite.

```bash
# Test full pipeline with docker-compose
docker-compose -f example/docker-compose.yml up -d

# Verify all services
docker-compose ps

# Run test suite
docker-compose exec apisix /path/to/tests/run.sh
```

--------------------------------

### Create .env File for Docker Compose

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/09-command-reference.md

Create a .env file to define environment variables for Docker Compose projects. This example sets the APISIX image tag and the compose project name.

```bash
# .env
APISIX_IMAGE_TAG=3.17.0-debian
COMPOSE_PROJECT_NAME=apisix-demo
```

--------------------------------

### Standalone APISIX YAML Configuration

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/08-deployment-scenarios.md

Example `apisix.yaml` file for standalone mode. Defines a route with a specific URI and upstream. Configuration changes in this file require a container restart or `apisix reload`.

```yaml
routes:
  - id: api_v1
    uri: /api/v1/*
    upstream:
      type: roundrobin
      nodes:
        "backend:8000": 1
```

--------------------------------

### Get Consumer

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/06-api-admin-endpoints.md

Retrieves a specific consumer by its username.

```APIDOC
## GET /apisix/admin/consumers/{username}

### Description
Retrieves a specific consumer by its username.

### Method
GET

### Endpoint
/apisix/admin/consumers/{username}

### Parameters
#### Path Parameters
- **username** (string) - Required - The username of the consumer to retrieve
```

--------------------------------

### Get Consumer

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/06-api-admin-endpoints.md

Retrieves a specific consumer by its username.

```http
GET /apisix/admin/consumers/{username}
```

--------------------------------

### Get Plugin Metadata

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/06-api-admin-endpoints.md

Retrieves the metadata and schema for a specific plugin.

```APIDOC
## GET /apisix/admin/plugins/{plugin_name}

### Description
Retrieves the configuration schema and metadata for a specific plugin.

### Method
GET

### Endpoint
/apisix/admin/plugins/{plugin_name}

### Parameters
#### Path Parameters
- **plugin_name** (string) - Required - The name of the plugin to retrieve metadata for

### Example
`GET /apisix/admin/plugins/rate-limit`
```

--------------------------------

### Get Node Information

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/06-api-admin-endpoints.md

Retrieves a list of cluster nodes and their metadata.

```http
GET /apisix/admin/nodes
```

--------------------------------

### Get Plugin Metadata

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/06-api-admin-endpoints.md

Retrieves the schema and metadata for a specific plugin.

```http
GET /apisix/admin/plugins/{plugin_name}
```

```http
Example: GET /apisix/admin/plugins/rate-limit
```

--------------------------------

### Get Route

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/06-api-admin-endpoints.md

Retrieves a specific route configuration by its unique identifier.

```APIDOC
## GET /apisix/admin/routes/{route_id}

### Description
Retrieves a specific route configuration by its unique identifier.

### Method
GET

### Endpoint
/apisix/admin/routes/{route_id}

### Parameters
#### Path Parameters
- **route_id** (string) - Required - Unique route identifier

### Response
#### Success Response (200)
- **Route object** - Single route object
```

--------------------------------

### Check APISIX Version

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/09-command-reference.md

Verify the installed APISIX version using docker-compose.

```bash
docker-compose exec apisix apisix version
# Output: APISIX 3.17.0
```

--------------------------------

### Initialize APISIX Runtime

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/09-command-reference.md

Initialize the APISIX runtime environment, including creating default directories. This command typically runs automatically during container startup.

```bash
docker-compose exec apisix apisix init
```

--------------------------------

### Standalone Mode Initialization Script

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/02-docker-entry-points.md

Initializes APISIX in standalone mode by creating configuration files if they do not exist, then runs the APISIX initialization command.

```bash
if [ "$APISIX_STAND_ALONE" = "true" ]; then
    # Create config.yaml if not present
    if [ ! -f "${PREFIX}/conf/config.yaml" ]; then
        cat > ${PREFIX}/conf/config.yaml << _EOC_
deployment:
  role: data_plane
  role_data_plane:
    config_provider: yaml
_EOC_
    fi

    # Create apisix.yaml if not present
    if [ ! -f "${PREFIX}/conf/apisix.yaml" ]; then
        cat > ${PREFIX}/conf/apisix.yaml << _EOC_
routes:
  -
#END
_EOC_
    fi

    /usr/bin/apisix init
fi
```

--------------------------------

### Docker Entrypoint Script Basic Structure

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/02-docker-entry-points.md

The main Docker entrypoint script for APISIX. It sets up environment variables and checks for the 'docker-start' command to initiate APISIX.

```bash
#!/usr/bin/env bash
set -eo pipefail

PREFIX=${APISIX_PREFIX:=/usr/local/apisix}

if [[ "$1" == "docker-start" ]]; then
    # Conditional initialization based on deployment mode
fi
```

--------------------------------

### Get Plugin Config

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/06-api-admin-endpoints.md

Retrieves a specific reusable plugin configuration by its ID.

```APIDOC
## GET /apisix/admin/plugin_configs/{config_id}

### Description
Retrieves a specific plugin config by its ID.

### Method
GET

### Endpoint
/apisix/admin/plugin_configs/{config_id}

### Parameters
#### Path Parameters
- **config_id** (integer) - Required - The ID of the plugin config to retrieve
```

--------------------------------

### Get Plugin Config

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/06-api-admin-endpoints.md

Retrieves a specific reusable plugin configuration by its ID.

```http
GET /apisix/admin/plugin_configs/{config_id}
```

--------------------------------

### Debug APISIX startup issues

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/12-quick-start-reference.md

A series of bash commands to debug APISIX startup problems, including checking container logs, searching for errors, verifying the process is running, and inspecting container state.

```bash
# 1. Check container logs
docker logs -f apisix

# 2. Look for error messages
docker logs apisix | grep -i "error\|failed"

# 3. Check if process started
docker ps | grep apisix

# 4. Inspect container state
docker inspect apisix | grep -A5 '"State"'
```

--------------------------------

### Get Service by ID

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/06-api-admin-endpoints.md

Retrieves a specific service configuration by its unique identifier.

```APIDOC
## GET /apisix/admin/services/{service_id}

### Description
Retrieves a specific service configuration by its unique identifier.

### Method
GET

### Endpoint
/apisix/admin/services/{service_id}

### Parameters
#### Path Parameters
- **service_id** (string) - Required - Unique service identifier

### Response
#### Success Response (200)
- **Service object** - Service object with configuration
```

--------------------------------

### Prometheus Metrics Endpoint

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/03-configuration-reference.md

Example of how to access the Prometheus metrics endpoint provided by APISIX.

```http
GET http://localhost:9091/apisix/prometheus/metrics
```

--------------------------------

### Get Node Information

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/06-api-admin-endpoints.md

Retrieves information about the APISIX cluster nodes, including their metadata.

```APIDOC
## GET /apisix/admin/nodes

### Description
Retrieves the cluster node list and metadata.

### Method
GET

### Endpoint
/apisix/admin/nodes
```

--------------------------------

### Initialize APISIX and etcd Schema

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/02-docker-entry-points.md

Use these commands to initialize APISIX runtime and etcd schema when not running in standalone mode. An external etcd cluster is expected.

```bash
/usr/bin/apisix init
/usr/bin/apisix init_etcd
```

--------------------------------

### Get Specific Route Configuration

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/09-command-reference.md

Retrieves the configuration for a specific route, identified by its key (e.g., /apisix/routes/route_1).

```bash
docker-compose exec etcd etcdctl get /apisix/routes/route_1
```

--------------------------------

### Request Rate Query

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/07-monitoring-observability.md

Use this PromQL query to get the request rate in requests per second.

```promql
rate(apisix_request_total[1m])
```

--------------------------------

### List Routes with Pagination

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/06-api-admin-endpoints.md

Demonstrates how to list routes using pagination parameters. Supports fetching specific pages of results with a defined page size.

```APIDOC
## GET /apisix/admin/routes/

### Description
Retrieves a paginated list of routes configured in APISIX.

### Method
GET

### Endpoint
/apisix/admin/routes/

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number to retrieve. Pages are 1-indexed for display.
- **page_size** (integer) - Optional - The number of items to return per page.

### Request Example
```bash
curl 'http://localhost:9180/apisix/admin/routes/?page=1&page_size=10'
```

### Response
#### Success Response (200)
- **node** (object) - Contains details of a single route if a single item is returned.
  - **key** (string) - The key of the route.
  - **value** (object) - The route configuration.
- **list** (array) - Contains a list of routes if multiple items are returned.
  - **key** (string) - The key of the route.
  - **value** (object) - The route configuration.
- **total** (integer) - The total number of routes available.
- **action** (string) - The action performed (e.g., "get").

#### Response Example
```json
{
  "list": [
    {"key": "...", "value": {...}},
    {"key": "...", "value": {...}}
  ],
  "total": 2
}
```
```

--------------------------------

### Route Disabled Example

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/11-troubleshooting-guide.md

Illustrates a route that is disabled, indicated by a 'status: 0'. Disabled routes will not process requests.

```yaml
status: 0  # Disabled
```

--------------------------------

### List APISIX routes with details

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/12-quick-start-reference.md

Use 'curl' and 'jq' to list all APISIX routes, filtering for ID, URI, and methods. This is helpful for debugging route-related issues.

```bash
# 1. List all routes
curl http://localhost:9180/apisix/admin/routes/ \
  -H 'X-API-KEY: key' | jq '.list[].node.value | {id, uri, methods}'
```

--------------------------------

### Check Built Docker Images

Source: https://github.com/apache/apisix-docker/blob/master/docs/en/latest/build.md

List all Docker images on your system to verify that the APISIX image was built successfully. Look for the repository and tag corresponding to your build.

```shell
docker images
```

--------------------------------

### Push Multi-Architecture Images on Ubuntu

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/05-build-process.md

Builds and pushes Docker images for both AMD64 and ARM64 architectures to a registry on an Ubuntu-based system. Requires Docker buildx and configured credentials.

```makefile
make push-multiarch-on-ubuntu
```

--------------------------------

### Copy CA Certificates

Source: https://github.com/apache/apisix-docker/blob/master/example/mkcert/README.md

Copies the root CA certificate and its key to the current directory. Ensure mkcert is installed and configured.

```bash
cp $(mkcert -CAROOT)/rootCA.pem .

cp $(mkcert -CAROOT)/rootCA-key.pem .
```

--------------------------------

### GET /apisix/prometheus/metrics

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/07-monitoring-observability.md

Retrieves Prometheus metrics from the APISIX instance. This endpoint is used by Prometheus to scrape metrics for monitoring and analysis.

```APIDOC
## GET /apisix/prometheus/metrics

### Description
Retrieves Prometheus metrics from the APISIX instance. This endpoint is used by Prometheus to scrape metrics for monitoring and analysis.

### Method
GET

### Endpoint
http://apisix:9091/apisix/prometheus/metrics

### Response
#### Success Response (200)
- **Return Type:** Plain text with MIME type `text/plain; version=0.0.4`

#### Response Example
```text
# HELP apisix_http_status Counter of HTTP status codes
# TYPE apisix_http_status counter
apisix_http_status{status="200"} 100
apisix_http_status{status="404"} 5
apisix_http_status{status="500"} 1

# HELP apisix_request_total Total number of requests
# TYPE apisix_request_total counter
apisix_request_total 106

# HELP apisix_request_duration_ms Request latency in milliseconds
# TYPE apisix_request_duration_ms histogram
apisix_request_duration_ms_bucket{le="1"} 50
apisix_request_duration_ms_bucket{le="100"} 105
apisix_request_duration_ms_bucket{le="+Inf"} 106
```
```

--------------------------------

### Docker Compose Full Stack APISIX Setup

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/README.md

This snippet shows how to deploy a full APISIX stack using Docker Compose, including the gateway, Prometheus metrics, Grafana, and the Admin API. It's suitable for more comprehensive local development and testing environments.

```bash
cd example
docker-compose -f docker-compose.yml up -d

# Access
curl http://localhost:9080/              # Gateway
curl http://localhost:9090/              # Prometheus metrics
curl http://localhost:3000/              # Grafana (admin/admin)
curl http://localhost:9180/apisix/admin/routes/ \
  -H 'X-API-KEY: edd1c9f034335f136f87ad84b625c8f1'  # Admin API
```

--------------------------------

### Build Red Hat Image

Source: https://github.com/apache/apisix-docker/blob/master/_autodocs/09-command-reference.md

Builds a Red Hat-based APISIX Docker image.

```bash
make build-on-redhat
```