Install with Docker Compose#

Use the deployment bundle to run POC Factory on a trusted single host. The bundle supplies Compose, an environment template, and launch preflight; application images come from the NVIDIA NGC catalog. Local Python, Node.js, and a source checkout are not required.

Prerequisites#

Prepare the host and credentials before starting the stack.

  1. Install Docker and the Compose plugin 2.24.0 or later. Check docker info and docker compose version.

  2. Reserve at least 8 GB RAM, 20 GB free disk, and host ports 80 and 8000; generated workloads may need more resources.

  3. Download the Compose deployment bundle and obtain image pull access for nvcr.io/nvidia.

  4. Obtain an OpenAI-compatible inference API key or plan to save a complete user profile in Settings. Default auto generation also needs a valid Cursor credential.

  5. Plan persistent PostgreSQL credentials, a stable encryption key, and backups of application data.

The Compose bundle mounts /var/run/docker.sock for generated-container build and runtime validation. Run it on a trusted host with access to that daemon. Support matrix describes the runtime and optional capability requirements.

Installation Methods#

Use the MCP profile for the standard stack; add Phoenix when you need tracing.

MCP profile

Follow this sequence for a new local evaluation deployment. Existing installations should follow Upgrade guide.

  1. Extract poc_factory-1.1.1.zip and open its poc_factory/ directory. Check that the Compose file, env.example, README.md, and scripts/validate-compose-env.sh are present.

  2. Initialize a new environment without replacing an existing file:

    test -f .env || cp env.example .env

  3. Generate an encryption key once, save it securely, and put it in .env:

    openssl rand -base64 32 | tr '+/' '-_' | tr -d '\n'

    The command prints a Fernet-compatible key. Preserve it across restarts and upgrades; do not generate a new value when repeating these steps.

  4. Edit .env with your values. Replace each placeholder with its actual value:

    NIM_NGC_ORG=nvidia
VERSION=1.1.1
INFERENCE_API_KEY=<your-inference-key>
ENCRYPTION_KEY=<the-stable-key-you-generated>
POSTGRES_USER=<service-user>
POSTGRES_PASSWORD=<strong-password>
POSTGRES_DB=pocfactory_db
ENVIRONMENT=development
NGC_AUTH_ENABLED=false
SECURE_COOKIES=false
OAUTH_ENABLED=false

    Put deployment values in .env so both Compose and the preflight container receive them. Preserve the shipped inference base URL and five model mappings unless you have verified replacements. These authentication-disabled HTTP settings are for private local evaluation only.

  5. Choose the generation credentials. For the default contract-first auto mode, save a Cursor key in Settings when user overrides are allowed. To supply an administrator key at launch, set both CURSOR_API_KEY and MODEL_CURSOR=auto (or an explicit supported Cursor model identifier) in .env. The Cursor credential is separate from the inference provider key.

  6. Authenticate to NGC. Enter an NGC API key authorized for these images at the password prompt:

    docker login nvcr.io --username '$oauthtoken'

  7. Inspect, pull, and start the release:

    docker compose --profile mcp config --images
docker compose --profile mcp pull
docker compose --profile mcp up -d
docker compose --profile mcp ps

    Confirm the three application images resolve to nvcr.io/nvidia/poc-factory-mcp:1.1.1, nvcr.io/nvidia/poc-factory-frontend:1.1.1, and nvcr.io/nvidia/github-mcp-proxy-nat-agentic-poc:1.1.1. PostgreSQL has its own tag. Remove older per-image overrides if they prevent the shared VERSION from selecting this release.

Full profile with Phoenix

Use the full profile to add tracing to the same application stack.

docker compose --profile full up -d

The frontend is at http://localhost, backend health at http://localhost:8000/health, and Phoenix at http://localhost:6006 when enabled. For shared access, configure HTTPS and authentication through Configure and validate.

Additional Setup#

Match optional services and generator policy to your workflow.

CODE_GENERATOR_TOOL=auto uses the contract-first Cursor path and does not silently fall back to another generator. If you intentionally want the separate inference-backed full-project mode, set CODE_GENERATOR_TOOL=llm. Some shipped template comments describe older fallback behavior; use the Support matrix as the mode reference.

Set a read-only GITHUB_TOKEN for authenticated MCP discovery if needed. Fine-tuning requires separately configured NeMo Microservices endpoints. Configure the full inference profile before generation: chat and embedding roles must both validate.

Installation Verification#

Run the checks below and inspect the observed result.

  1. Check container status and backend health:

    docker compose --profile mcp ps
curl -fsS http://localhost:8000/health

    The health response should report healthy, the selected application version, and healthy database and state-manager checks.

  2. Open http://localhost and confirm the frontend loads. Configure and validate inference and Cursor in Settings as required by the deployment policy.

  3. Follow Generate your first POC. Confirm a record on Dashboard, a downloadable archive, and explicit validation results.

  4. Restart the stack, then verify that the POC remains visible and downloadable and saved credentials remain usable.

A healthy endpoint proves service health; the POC and restart checks exercise generation and persistence.

Troubleshoot the Installation#

If preflight fails, inspect the named variable in the logs and put it in .env. For pull errors, check NGC permissions, nvidia, the selected image tag, and CPU architecture. If code generation fails, check the Cursor credential and administrator MODEL_CURSOR setting. See Troubleshooting.

Next Steps#

After the first successful workflow, Configure and validate the full deployment and record which candidate checks ran. Read Operate and restore before using the service with retained team data.