Version: v1

Custom App Configuration

You can use a combination of docker compose, profiles, configuration files, and environment variables to customize the behavior of the DevPortal instance.

The recommended approach is to mount a custom app-config.local.yaml file. This lets you override default settings without modifying the container image.

Config File Precedence

All configuration files are loaded and merged in this order (later entries override earlier ones):

app-config.yaml — base image defaults
app-config.production.yaml — production overrides baked into image
app-config.{profile}.yaml — profile-specific config (if VEECODE_PROFILE is set)
app-config.distro.yaml — distro-level overrides (baked in)
app-config.local.yaml ← your custom file, mounted at /app/app-config.local.yaml
dynamic-plugins-root/app-config.dynamic-plugins.yaml — generated at startup by the plugin install script
app-config.saas.yaml — SaaS mode only; decoded from VEECODE_APP_CONFIG

Your app-config.local.yaml (layer 5) wins over the base and profile defaults, but plugin-injected config (layer 6) is loaded after it. If a setting in local.yaml seems to be ignored, check whether an enabled plugin's pluginConfig block is overriding it.

Creating a Custom Config File

Create an app-config.local.yaml file in your project directory:

app:
  title: My Company DevPortal
  baseUrl: http://localhost:7007

organization:
  name: My Company

backend:
  baseUrl: http://localhost:7007
  listen:
    port: 7007
  cors:
    origin: http://localhost:7007
    methods: [GET, HEAD, PATCH, POST, PUT, DELETE]
    credentials: true

# Example: Configure GitHub integration
integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}

# Example: Add a catalog location
catalog:
  locations:
    - type: url
      target: https://github.com/your-org/your-repo/blob/main/catalog-info.yaml

Mounting with Docker Run

Use the -v flag to mount your config file:

docker run --rm --name devportal -d \
  -p 7007:7007 \
  -v $(pwd)/app-config.local.yaml:/app/app-config.local.yaml:ro \
  veecode/devportal:latest

Mounting with Docker Compose

Update your docker-compose.yml:

services:
  devportal:
    image: veecode/devportal:latest
    ports:
      - "7007:7007"
    environment:
      - GITHUB_TOKEN=${GITHUB_TOKEN}
    volumes:
      - ./app-config.local.yaml:/app/app-config.local.yaml:ro

Then run:

docker compose up -d

Development Mode

Set DEVELOPMENT=true to enable nodemon hot-reload. DevPortal will watch app-config.yaml, app-config.production.yaml, app-config.local.yaml, and the generated dynamic-plugins-root/app-config.dynamic-plugins.yaml for changes and restart automatically:

services:
  devportal:
    image: veecode/devportal:latest
    ports:
      - "7007:7007"
    environment:
      - DEVELOPMENT=true
    volumes:
      - ./app-config.local.yaml:/app/app-config.local.yaml:ro

You can also expose the Node.js debugger by setting DEBUG_PORT:

    environment:
      - DEVELOPMENT=true
      - DEBUG_PORT=9229
    ports:
      - "7007:7007"
      - "9229:9229"

Common Configuration Examples

GitHub Authentication

auth:
  environment: development
  providers:
    github:
      development:
        clientId: ${GITHUB_AUTH_CLIENT_ID}
        clientSecret: ${GITHUB_AUTH_CLIENT_SECRET}

Database Configuration

backend:
  database:
    client: pg
    connection:
      host: ${POSTGRES_HOST}
      port: ${POSTGRES_PORT}
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}

Environment Variables

You can reference environment variables in your config file using the ${VAR_NAME} syntax. Pass them via Docker:

docker run --rm --name devportal -d \
  -p 7007:7007 \
  -e GITHUB_TOKEN=your_token_here \
  -v $(pwd)/app-config.local.yaml:/app/app-config.local.yaml:ro \
  veecode/devportal:latest