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
OSA_PROXY_URL_FROM_FORWARDED_HEADERS=false
CODESCORING_BLOCK_MESSAGE=
CODESCORING_APPEND_BLOCK_URL_TO_MESSAGE=true
LEGACY_JUDGE=false
LOG_LEVEL=info
CACHE_ENABLED=false
REDIS_ADDRESS=redis:6379
REDIS_USERNAME=
REDIS_PASSWORD=
REDIS_DB=0
REDIS_SENTINEL_ENABLED=false
REDIS_SENTINEL_MASTER_NAME=
REDIS_SENTINEL_USERNAME=
REDIS_SENTINEL_PASSWORD=
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}
osa-proxy-url-from-forwarded-headers: ${OSA_PROXY_URL_FROM_FORWARDED_HEADERS:false}
block-message: ${CODESCORING_BLOCK_MESSAGE:}
append-block-url-to-message: ${CODESCORING_APPEND_BLOCK_URL_TO_MESSAGE:true}
legacy-judge: ${LEGACY_JUDGE:false}
cache:
judge:
enabled: ${CACHE_ENABLED:false}
redis:
address: ${REDIS_ADDRESS:redis:6379}
username: ${REDIS_USERNAME:}
password: ${REDIS_PASSWORD:}
db: ${REDIS_DB:0}
sentinel:
enabled: ${REDIS_SENTINEL_ENABLED:false}
master-name: ${REDIS_SENTINEL_MASTER_NAME:}
addresses:
- sentinel-1.example.com:26379
- sentinel-2.example.com:26379
username: ${REDIS_SENTINEL_USERNAME:}
password: ${REDIS_SENTINEL_PASSWORD:}
logging:
level: ${LOG_LEVEL:info}
cache.redis.sentinel.addresses is a regular YAML list. Add as many Sentinel endpoints as required. To provide addresses through the environment, use a custom ${VAR_NAME} placeholder for each list item.
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
block-status-code: 403
npm:
enabled: true
repository:
- name: npm
registry: https://registry.npmjs.org
scan-manifest: true
remove-blocked-versions: true
scan-package: true
work-mode: strict_wait
logging:
level: info
After installation, check the endpoints:
curl https://osa-proxy.example.com/healthz
curl https://osa-proxy.example.com/metrics
