OpenCore

Deployment Quickstart

View as Markdown

The guided installers prepare a Docker Compose deployment, generate the local environment file, select a free host port, pull the requested images, and start the services. Run the script that matches the host operating system.

Prerequisites

RequirementmacOS or LinuxWindows
ShellBash 3.2 or laterPowerShell 5 or later
DownloaderAt least one of curl or wgetPowerShell Invoke-WebRequest, included with the supported PowerShell version
ContainersRunning Docker daemon and Docker Compose 2.24 or laterDocker Desktop or another Linux-container Docker environment, with Docker Compose 2.24 or later
Recommended Standard resources10 GB Docker memory and 32 GB free disk10 GB Docker memory and 32 GB free disk
RepositoryA trusted local checkout of the OpenCore repositoryA trusted local checkout of the OpenCore repository

The Unix installer also uses OpenSSL to generate local secrets. Keep the generated .env file private and out of source control.

Choose a mode

ModeServicesSupported knowledge featuresHow to select it
LiteDoes not start OpenSearch, Redis, model servers, or background workersConnectors and RAG search are disabled; chat, tools, file uploads, Projects, Agent knowledge, and code interpreter remain availableAccept interactive choice 1, or use --lite on Unix and -Lite on Windows
StandardStarts the full search and indexing deploymentOpenSearch-backed search, connectors, indexing, and RAG are availableRun interactively and choose 2

The interactive default is Lite. There is no Standard command-line switch, and --no-prompt or -NoPrompt accepts defaults, including Lite. Use the interactive mode prompt when installing Standard.

See Deployment Modes before choosing Lite for an environment that may later need connectors or indexed knowledge.

Install

Use a neutral installation directory through INSTALL_PREFIX; the examples below create opencore_data beneath the directory where the script runs.

macOS or Linux

From the repository root:

$cd deployment/docker_compose
$chmod +x install.sh
$INSTALL_PREFIX=opencore_data ./install.sh

Windows

From the repository root in PowerShell:

1Set-Location deployment\docker_compose
2$env:INSTALL_PREFIX = "opencore_data"
3.\install.ps1

The installers prompt for deployment mode and image tag, create opencore_data/deployment/.env, use basic authentication for a new deployment, and generate the local authentication secret. Common inputs are:

ActionmacOS or LinuxWindowsBehavior
Select Lite directly--lite-LiteSkips the Standard search and indexing services
Enable Craft--include-craft-IncludeCraftEnables Craft; cannot be combined with Lite
Reuse downloaded configuration--local-LocalRequires the expected configuration files to exist in the installation directory
Accept defaults without prompts--no-prompt-NoPromptUses defaults, including Lite mode
Preview without changes--dry-run-DryRunPrints the planned installation and exits
Show diagnostic detail--verbose-ShowVerboseEnables more detailed installer output

On Unix, --no-wait returns after the containers start instead of waiting up to 600 seconds for health checks. Do not treat that return as proof that every service is ready.

Verify services

  1. From the directory where you ran the installer, inspect the generated deployment:

    $cd opencore_data/deployment
    $docker compose ps

  2. Confirm the expected containers are running. Standard should include OpenSearch and the search/indexing workers; Lite intentionally omits them.

  3. Open the URL printed by the installer. It starts at http://localhost:3000 and selects the next free port when 3000 is already occupied.

  4. Open /auth/signup on that host to create the first account. The first created user receives administrator privileges.

Upgrade

Stop the current deployment with the same installation prefix before changing its image tag. Return to deployment/docker_compose in the repository checkout before running these commands.

macOS or Linux

$INSTALL_PREFIX=opencore_data ./install.sh --shutdown
$INSTALL_PREFIX=opencore_data ./install.sh

Windows

1$env:INSTALL_PREFIX = "opencore_data"
2.\install.ps1 -Shutdown
3.\install.ps1

When the installer finds the existing .env, choose update, select the target tag, and repeat the original Lite or Standard selection. Floating tags are pulled and recreated; a pinned tag also causes the installer to obtain matching deployment configuration when downloads are enabled. Verify service health again after the restart.

Troubleshooting

SymptomCheck
The installer refuses a configuration changeServices are still running. Use the script’s shutdown option with the same INSTALL_PREFIX, then rerun it.
Docker Compose cannot parse env_fileUpgrade Docker Compose to 2.24 or later.
The expected page is not on port 3000Read the final installer output; it automatically chooses the next available host port.
A Standard knowledge feature is missingConfirm that Standard was selected. Lite does not start OpenSearch, connectors, or RAG search.
A service is unhealthyRun docker compose ps and docker compose logs <service> from the generated deployment directory.