Frontend Configuration

The oCore frontend is a Next.js application. Configuration is provided through NEXT_PUBLIC_ environment variables which are embedded into the JavaScript bundle at build time.

Build-Time Variables

Next.js inlines NEXT_PUBLIC_* variables into the client-side bundle during next build. This means:

• Variables must be set when building the Docker image, not when running the container
• Changing a variable requires rebuilding the frontend image
• Variables are visible in the browser (they are not secrets)

Docker Build Args

In the production Docker Compose file, frontend variables are passed as build args:

services:
  frontend:
    build:
      context: .
      dockerfile: Dockerfile.frontend
      args:
        NEXT_PUBLIC_API_URL: ${NEXT_PUBLIC_API_URL}
        NEXT_PUBLIC_SSH_PORT: ${NEXT_PUBLIC_SSH_PORT:-2222}

The Dockerfile reads these args and sets them as environment variables during the build:

ARG NEXT_PUBLIC_API_URL
ARG NEXT_PUBLIC_SSH_PORT=2222
ENV NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL}
ENV NEXT_PUBLIC_SSH_PORT=${NEXT_PUBLIC_SSH_PORT}
RUN pnpm build

Variable Reference

NEXT_PUBLIC_API_URL

This is the most important frontend configuration. It tells the browser where to send API requests.

Correct values:

# If reverse proxy routes /api to the backend on the same domain
NEXT_PUBLIC_API_URL=https://ocore.example.com

# If the backend is on a separate subdomain
NEXT_PUBLIC_API_URL=https://api.ocore.example.com

Common mistakes:

# WRONG: Docker-internal hostname (not accessible from browser)
NEXT_PUBLIC_API_URL=http://backend:8080

# WRONG: localhost (only works on the server itself)
NEXT_PUBLIC_API_URL=http://localhost:8080

# WRONG: Missing protocol
NEXT_PUBLIC_API_URL=ocore.example.com

The URL must be reachable from the end user's browser, not from inside the Docker network.

NEXT_PUBLIC_SSH_PORT

Displayed in the dashboard when users copy SSH connection strings:

ssh -p 2222 user@ocore.example.com

If you expose the SSH gateway on a non-standard port (e.g., behind a firewall rule mapping 22222 to 2222), set this to the externally visible port.

Rebuilding After Configuration Changes

When you change a NEXT_PUBLIC_* variable, you must rebuild the frontend:

# Rebuild only the frontend service
docker compose -f docker-compose.prod.yml build frontend

# Restart with the new image
docker compose -f docker-compose.prod.yml up -d frontend

The backend does not need to be rebuilt or restarted when frontend variables change.

Development Configuration

For local development, create a .env.local file in the frontend/ directory:

NEXT_PUBLIC_API_URL=http://localhost:8080
NEXT_PUBLIC_SSH_PORT=2222

Next.js automatically loads .env.local during next dev and next build. This file is gitignored and should not be committed.

Runtime vs Build-Time

oCore's frontend uses only build-time variables because all configuration values are non-sensitive and need to be available in the browser for API calls and UI display.