Skip to content

docker.md

Latest commit

 

History

History
295 lines (192 loc) · 6.3 KB

docker.md

File metadata and controls

295 lines (192 loc) · 6.3 KB
Raw

Docker Deployment Guide

This document describes how to run WebAI-to-API using Docker and how to configure authentication for browser-based providers.

The built-in dashboard under /ui/* is also exposed by the service. If you map the service port to a public interface, you expose the dashboard routes as well. See Dashboard Guide for the dashboard security posture and available pages.

Prerequisites

Required software:

  • Docker
  • Docker Compose
  • GNU Make (optional)

Environment Configuration

WebAI-to-API uses two primary configuration files:

  1. .env: Used by Docker Compose to set environment variables (e.g., ATLASCLOUD_API_KEY).
  2. config.conf: Used by the application for detailed settings (e.g., Gemini backend, proxy).

Create Configuration

Run the bootstrap utility to create default configurations:

python scripts/bootstrap.py

Alternatively, copy the examples manually:

cp .env.example .env
cp config.conf.example config.conf

Note: config.conf is mounted read-only into the container and .env is loaded by Docker Compose via env_file. They must exist as files on your host machine before starting the container; if they are missing, Docker Compose may incorrectly create them as directories, causing the application to fail. Run python scripts/bootstrap.py to ensure they are correctly initialized.

Changes to config.conf or .env on the host are reflected in the container after a restart; an image rebuild is not required for configuration-only updates. Do NOT commit config.conf or .env as they may contain secrets.

Container Logging Controls

Container logging is configured via environment variables passed into the service. By default, the container logs at INFO level and outputs web request access logs to stderr.

You can override these behaviors by passing environment variables:

  • Default Run (INFO level logs, access logs enabled): 
    docker compose up
  • Enable Container DEBUG Logs: 
    LOG_LEVEL=DEBUG docker compose up
  • Disable HTTP Request Access Logs: 
    DISABLE_ACCESS_LOGS=true docker compose up

Build

Build the Docker image:

make build

Force a clean rebuild:

make build-fresh

Run

Start the stack:

make up

Start the stack in the foreground:

make up-attach

Follow container logs from an already running stack:

make logs

Stop the stack:

make stop

Playwright Authentication

Playwright-based models require browser authentication before the container starts.

Authentication must be generated on the host machine.

Generate Authentication

Install dependencies and prepare the environment:

poetry install
poetry run playwright install chromium
cp config.conf.example config.conf

Note: You can also use make setup as a shortcut.

Run the authentication workflow:

python verify_login.py

A browser window will open.

  1. Sign in to your Google account.
  2. Wait until Gemini is accessible.
  3. Return to the terminal and complete the workflow.

Authentication state will be stored in:

runtime/auth/gemini.json

Verify the file exists:

ls runtime/auth/gemini.json

Start Docker

After authentication has been generated:

make build
make up

Verify authentication status:

curl http://localhost:6969/v1/auth/status

Using Playwright Models

Example request:

curl -X POST http://localhost:6969/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "playwright/gemini-3-flash",
    "messages": [
      {
        "role": "user",
        "content": "Hello!"
      }
    ]
  }'

Gemini WebAPI and Playwright support request-scoped Extended Thinking through provider_options.gemini.extended_thinking; see API Documentation for request format and semantics.

Configuration & Persistence

The Docker configuration uses bind mounts to persist data and load settings:

./config.conf:/app/config.conf:ro
./runtime:/app/runtime

1. Configuration (config.conf)

The config.conf file is mounted read-only. It contains your backend selections, manual cookies, and engine tuning. Because it is mounted at runtime, it is NOT baked into the Docker image, ensuring your secrets remain on your host machine.

2. Authentication State (runtime/auth/gemini.json)

Authentication generated by verify_login.py is stored in the runtime/ directory.

3. Lifecycle

As long as these files/directories are preserved on the host, configuration and authentication survive:

  • Container restarts
  • Container recreation
  • Image rebuilds
  • Host reboots

Refreshing Authentication

If authentication expires:

poetry run python verify_login.py

Then restart the container:

make stop
make up

Authentication is loaded when a new Playwright browser context is created.

Updating runtime/auth/gemini.json while the container is running does not update existing browser contexts.

Frequently Asked Questions

Can authentication be generated inside Docker?

No.

The login workflow requires an interactive browser and must be performed on the host machine.

Does authentication survive container recreation?

Yes.

Authentication is persisted through the mounted runtime directory.

Can authentication be refreshed without restarting Docker?

No.

After generating a new authentication state, restart the container so a new browser context can be created.

Runtime Persistence

The runtime directory stores persistent runtime state, including:

  • Authentication state
  • Session persistence
  • Runtime cache data

For Playwright deployments, preserving this directory is recommended.

File Layout

.
├── Dockerfile
├── docker-compose.yml
├── .env
├── config.conf
├── Makefile
└── runtime/

Best Practices

  • Generate Playwright authentication on the host machine.
  • Preserve the runtime directory between deployments.
  • Restart containers after refreshing authentication.
  • Use health and readiness endpoints for monitoring.
  • Do not expose the service port publicly unless you also secure the /ui/* dashboard routes with an external access-control layer.