Service deployment

OSA Proxy implementation

This page describes the current OSA Proxy implementation. The archived Java/Spring implementation is available in Archived Java/Spring implementation.

OSA Proxy uses the osa-proxy.yml configuration file. By default, the service looks for it in the working directory, but the path can be passed as the first startup argument or through the OSA_PROXY_CONFIG_PATH environment variable.

Legacy Judge compatibility

Before starting the current OSA Proxy with CodeScoring versions earlier than 2026.20.0, set codescoring.legacy-judge: true in osa-proxy.yml. Versions before 2026.20.0 use the legacy Judge API, while OSA Proxy uses the current Judge API by default.

Docker

Example container run with an external configuration file:

docker run -d \
  --name osa-proxy \
  -p 8080:8080 \
  -e OSA_PROXY_CONFIG_PATH=/etc/osa-proxy/osa-proxy.yml \
  -v /path/to/osa-proxy.yml:/etc/osa-proxy/osa-proxy.yml:ro \
  <registry-url>/osa-proxy:<tag>

Availability check:

curl http://localhost:8080/healthz

Docker Compose

services:
  osa-proxy:
    image: <registry-url>/osa-proxy:<tag>
    container_name: osa-proxy
    ports:
      - "8080:8080"
    env_file:
      - .env
    environment:
      OSA_PROXY_CONFIG_PATH: /etc/osa-proxy/osa-proxy.yml
    volumes:
      - ./osa-proxy.yml:/etc/osa-proxy/osa-proxy.yml:ro
    healthcheck:
      test: ["CMD", "/app/osa-proxy", "healthcheck"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 5s

If Redis verdict cache is enabled, add Redis to the Compose file and set its address in cache.redis.address.

`.env` file

When running with Docker Compose, .env is passed into the container only when it is listed in env_file. These variables can be used:

directly as process environment variables;
in osa-proxy.yml through ${VAR_NAME:default_value} placeholders.

In the Compose example, the configuration path is set separately through environment.OSA_PROXY_CONFIG_PATH, so do not duplicate it in .env.

Example .env:

CODESCORING_URL=https://codescoring.example.com
CODESCORING_TOKEN=
WORK_MODE=strict_wait
OSA_PROXY_URL=https://osa-proxy.example.com
LEGACY_JUDGE=false
LOG_LEVEL=info

CACHE_ENABLED=false
REDIS_ADDRESS=redis:6379
REDIS_PASSWORD=
REDIS_DB=0

Example usage in osa-proxy.yml:

codescoring:
  url: ${CODESCORING_URL:https://codescoring.example.com}
  token: ${CODESCORING_TOKEN:}
  work-mode: ${WORK_MODE:strict_wait}
  osa-proxy-url: ${OSA_PROXY_URL:http://localhost:8080}
  legacy-judge: ${LEGACY_JUDGE:false}

cache:
  judge:
    enabled: ${CACHE_ENABLED:false}
  redis:
    address: ${REDIS_ADDRESS:redis:6379}
    password: ${REDIS_PASSWORD:}
    db: ${REDIS_DB:0}

logging:
  level: ${LOG_LEVEL:info}

Store secrets in .env, not as literal values in osa-proxy.yml.

Proxy settings for outgoing HTTP requests

OSA Proxy uses standard Go HTTP clients. They automatically respect the HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables; lowercase variants http_proxy, https_proxy, and no_proxy can also be used.

Example .env for a corporate proxy:

HTTP_PROXY=http://proxy.company.example:3128
HTTPS_PROXY=http://proxy.company.example:3128
NO_PROXY=localhost,127.0.0.1,::1,redis,codescoring.example.com,.svc,.cluster.local

NO_PROXY should include addresses that the service must reach directly: local addresses, Redis, internal Kubernetes/Docker DNS names, internal CodeScoring domains, or internal package registries that should not go through the corporate proxy.

Additional CA Certificates

If OSA Proxy needs to connect to resources that use self-signed or corporate root CAs, mount the additional CA certificates into the container and add their directory to SSL_CERT_DIR.

The SSL_CERT_DIR value must include both the system CAs inside the container and the directory with additional certificates:

SSL_CERT_DIR=/etc/ssl/certs:/etc/osa-proxy/certs

Where:

/etc/ssl/certs is the system CA directory inside the container;
/etc/osa-proxy/certs is the directory with additional self-signed or corporate root CAs in PEM/CRT format.

Docker Compose example:

services:
  osa-proxy:
    image: <registry-url>/osa-proxy:<tag>
    environment:
      OSA_PROXY_CONFIG_PATH: /etc/osa-proxy/osa-proxy.yml
      SSL_CERT_DIR: /etc/ssl/certs:/etc/osa-proxy/certs
    volumes:
      - ./osa-proxy.yml:/etc/osa-proxy/osa-proxy.yml:ro
      - ./certs:/etc/osa-proxy/certs:ro

Helm

Minimal values.yaml example:

image:
  repository: <registry-url>/osa-proxy
  tag: "<tag>"

service:
  type: ClusterIP
  port: 8080

probes:
  enabled: true
  path: /healthz

ingress:
  enabled: true
  className: nginx
  hosts:
    - host: osa-proxy.example.com
      paths:
        - path: /
          pathType: Prefix

config:
  create: true
  key: osa-proxy.yml
  mountPath: /etc/osa-proxy/osa-proxy.yml
  content: |
    codescoring:
      url: https://codescoring.example.com
      token: "<token>"
      work-mode: strict_wait
      osa-proxy-url: https://osa-proxy.example.com
      block-on-codescoring-errors: true
      remove-blocked-versions: true
      block-status-code: 403

    npm:
      enabled: true
      repository:
        - name: npm
          registry: https://registry.npmjs.org
          scan-manifest: true
          scan-package: true
          work-mode: strict_wait
          url-encoded-config: true

    logging:
      level: info

After installation, check the endpoints:

curl https://osa-proxy.example.com/healthz
curl https://osa-proxy.example.com/metrics

Was this page helpful?

#Service deployment

#Docker

#Docker Compose

#.env file

#Proxy settings for outgoing HTTP requests

#Additional CA Certificates

#Helm