nethcti-middleware

nethcti-middleware

Migration status annotations

When a legacy nethcti-server endpoint is replaced by a new path in this middleware, add @migration-replaces annotations in main.go directly above the route definition. These annotations are read automatically by the NethVoice migration status dashboard.

Format

// @migration-replaces: METHOD /legacy/path
// @migration-note: Optional explanation of why the path changed.
api.METHOD("/new/path", methods.Handler)

• @migration-replaces — required. Must include the HTTP method and the full legacy path. Add one line per legacy path if the new endpoint replaces multiple old ones.
• @migration-note — optional. Free-form description of the change.

The annotation block may contain blank lines and plain // comments between entries, but must not be interrupted by any other code before the route line.

Example

// @migration-replaces: POST /authentication/phone_island_token_login
// @migration-note: Replaced by the new persistent token API.
api.POST("/tokens/persistent/:audience", methods.CreatePersistentToken)

Note: Annotations are only needed when the path changes. If the middleware exposes the exact same path as the legacy server, the dashboard detects it automatically.

Configuration

The application can be configured using the following environment variables:

Testing

Prerequisites

• Go 1.26 or later
• oathtool package (for 2FA testing)
• MariaDB 10.5+ or MySQL 8.0+ (for phonebook and persistence features)

Install oathtool on Ubuntu/Debian:

sudo apt-get install oathtool

Running Tests

Run all tests:

go test ./...

Run tests with verbose output:

go test -v ./...

Test Environment

Tests automatically create a temporary test environment with:

• Mock NetCTI server for authentication testing
• Temporary secrets directory (/tmp/test-secrets)
• Test JWT secret key
• Clean state for each test

The test suite covers:

• Authentication and login flows
• 2FA setup, verification, and management
• JWT token handling
• Recovery codes functionality
• Error handling and edge cases

Container Management

Stop and Clean Up

Stop the existing container and clean up system resources:

podman stop nethcti-container
podman system prune --all --volumes --force

Build Image

Build the Docker image:

podman build -t nethcti-middleware .

Run Container

Before running the middleware, ensure MariaDB is available and configured:

podman run -d --name mariadb-nethcti \
  --env MARIADB_ROOT_PASSWORD=your-secure-password \
  --env MARIADB_DATABASE=nethcti_middleware \
  -p 3306:3306 \
  mariadb:latest

Run the container with environment configuration:

podman run -d -p 8080:8080 --name nethcti-container \
  --env NETHVOICE_MIDDLEWARE_LISTEN_ADDRESS=:8080 \
  --env NETHVOICE_MIDDLEWARE_V1_PROTOCOL=https \
  --env NETHVOICE_MIDDLEWARE_V1_API_ENDPOINT=your-api-endpoint.example.com \
  --env NETHVOICE_MIDDLEWARE_V1_WS_ENDPOINT=your-ws-endpoint.example.com \
  --env NETHVOICE_MIDDLEWARE_V1_API_PATH=/webrest \
  --env NETHVOICE_MIDDLEWARE_V1_WS_PATH=/socket.io \
  --env NETHVOICE_MIDDLEWARE_SECRETS_DIR=/var/log/nethcti \
  --env NETHVOICE_MIDDLEWARE_MARIADB_HOST=mariadb \
  --env NETHVOICE_MIDDLEWARE_MARIADB_PORT=3306 \
  --env NETHVOICE_MIDDLEWARE_MARIADB_USER=root \
  --env NETHVOICE_MIDDLEWARE_MARIADB_PASSWORD=your-secure-password \
  --volume ./data:/var/log/nethcti \
  --replace nethcti-middleware