Apache APISIX Dashboard Documentation

The recommended way to develop Apache APISIX Dashboard is using VS Code with the Dev Containers extension. This approach provides a pre-configured environment containing git, node, pnpm, apisix, and etcd via the .devcontainer configuration.

Prerequisites

• Install VS Code.
• Install the Dev Containers extension in VS Code.

Setup Steps

1. Clone the repository:

   git clone https://github.com/apache/apisix-dashboard.git
   cd apisix-dashboard
   code .

2. Reopen in Container:
   • When VS Code opens, click the Reopen in Container prompt in the bottom right corner.
   • If no prompt appears, open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P), type reopen, and select Dev Containers: Reopen in Container.
3. Wait for build: Wait for the environment to build. You will see confirmation in the TERMINAL tab once it is ready.

The e2e/server/docker-compose.yml file provides a configuration for orchestrating a local development or end-to-end testing environment consisting of the APISIX service and an etcd instance.

Key components:

• apisix: Built from the repository root using the Dockerfile located at e2e/server/Dockerfile. It relies on a local apisix_conf.yml mounted as a read-only volume to /usr/local/apisix/conf/config.yaml. It exposes port 9180.
• etcd: Uses the bitnamilegacy/etcd:3.5 image. It is configured with etcd v2 enabled and no authentication required for testing purposes. Data is persisted in the etcd_data volume.
• Network: Both services communicate over a bridge network named apisix.

services:
  apisix:
    build:
      context: ../..
      dockerfile: e2e/server/Dockerfile
    restart: always
    volumes:
      - ./apisix_conf.yml:/usr/local/apisix/conf/config.yaml:ro
    ports:
      - '9180:9180'
    depends_on:
      - etcd
    networks:
      - apisix

  etcd:
    image: bitnamilegacy/etcd:3.5
    restart: always
    volumes:
      - etcd_data:/bitnami/etcd
    environment:
      ETCD_ENABLE_V2: 'true'
      ALLOW_NONE_AUTHENTICATION: 'yes'
      ETCD_ADVERTISE_CLIENT_URLS: 'http://etcd:2379'
      ETCD_LISTEN_CLIENT_URLS: 'http://0.0.0.0:2379'
    networks:
      - apisix

networks:
  apisix:
    driver: bridge

volumes:
  etcd_data:

The project uses Playwright for end-to-end (E2E) testing. The configuration is defined in playwright.config.ts and uses the following key settings:

• Test Directory: Tests are located in ./e2e/tests.
• Output Directory: Test results are stored in ./test-results.
• Execution Mode: Tests run in fullyParallel mode.
• CI Behavior:
  • forbidOnly is enabled when process.env.CI is present.
  • retries is set to 2 in CI, otherwise 0.
  • workers is limited to 1 in CI to ensure stability.
• Reporters: Uses html, list, and @estruyf/github-actions-reporter (with useDetails: true and showError: true).
• Base URL: The baseURL is dynamically set from the E2E_TARGET_URL environment variable.
• Tracing: Traces are captured on-first-retry.

import { defineConfig, devices } from '@playwright/test';
import { env } from './e2e/utils/env';

export default defineConfig({
  testDir: './e2e/tests',
  outputDir: './test-results',
  fullyParallel: true,
  forbidOnly: !!process.env.CI,
  retries: process.env.CI ? 2 : 0,
  workers: process.env.CI ? 1 : undefined,
  reporter: [
    ['html'],
    ['list'],
    ['@estruyf/github-actions-reporter', { useDetails: true, showError: true }],
  ],
  use: {
    baseURL: env.E2E_TARGET_URL,
    trace: 'on-first-retry',
  },
  projects: [
    {
      name: 'chromium',
      use: {
        ...devices['Desktop Chrome'],
        viewport: { width: 1920, height: 1080 },
        permissions: ['clipboard-read'],
      },
    },
  ],
});

The project uses a flat configuration system via typescript-eslint to enforce code quality across different file types. The configuration is divided into several specialized rule sets:

• Common Rules: Applies to all files. Includes recommended JS and TypeScript rules, enforces single quotes, and requires Apache Software Foundation (ASF) license headers (sourced from .actions/ASFLicenseHeader.txt).
• Import Rules: Enforces strict import sorting and manages unused imports. Unused variables/arguments starting with an underscore (^_) are ignored.
• E2E Rules: Targets e2e/**/*.ts and e2e/**/*.spec.ts files, incorporating Playwright recommended configurations.
• i18n Rules: Targets src/**/*.{ts,tsx,js}. Enforces internationalization best practices using i18next and @m6web/eslint-plugin-i18n. It specifically checks for unknown keys, prevents raw text as children (except for specific patterns), and restricts text in certain attributes like alt and title.
• Source Rules: Targets src/**/*.{ts,tsx} and eslint.config.ts. Enforces React best practices, React Hooks rules, and React Refresh requirements for Fast Refresh support.