---
title: "Docker Deployment"
description: "Deploy OpnForm using Docker"
---

import CloudVersion from "/snippets/cloud-version.mdx";

<CloudVersion />

<Tip>
    Looking to develop OpnForm locally? Check out our [Docker Development
    Setup](/deployment/docker-development) guide which provides hot-reload and
    other development features.
</Tip>

## Quick Start

1. Clone the repository:
    ```bash
    git clone https://github.com/OpnForm/OpnForm.git
    cd OpnForm
    ```

<Warning>
    **Important for Windows Users**: Ensure script files maintain LF
    (Unix-style) line endings. If you're using Windows, configure Git to
    preserve line endings: ```bash git config core.autocrlf false ``` And
    check/fix the artisan script before running setup: ```bash # Using Git Bash
    or WSL dos2unix api/artisan ``` Otherwise, Docker containers may hang at
    "Waiting for DB to be ready" during startup.
</Warning>

2. Run the setup script:

    ```bash
    chmod +x scripts/docker-setup.sh
    ./scripts/docker-setup.sh
    ```

    The script will:

    - Create necessary environment files
    - Pull required Docker images
    - Start all containers in production mode
    - Display access information

3. Access your OpnForm instance at `http://localhost`

### Initial Setup

After deployment, OpnForm will automatically redirect you to a setup page where you can create your admin account. Simply visit `http://localhost` and you'll be guided through the setup process.

<Note>
    Public registration is disabled in the self-hosted version after setup is
    complete. Use the admin account to invite additional users. Free
    self-hosted instances are limited to 2 users total across the instance;
    activate a self-hosted Enterprise license to add more users.
</Note>

<Info>
    A self-hosted Enterprise license is optional. Core self-hosted OpnForm works
    without a license, including OIDC within the free 2-user limit. Adding more
    users and advanced Enterprise features require license activation. See
    [Self-hosted License](/deployment/self-hosted-license).
</Info>

## Architecture

```mermaid
graph TD
    A[Nginx Proxy] --> B[Frontend - Nuxt SSR]
    A --> C[Backend - Laravel API]
    C --> D[PostgreSQL]
    C --> E[Redis]
    C --> F[Queue Worker]
    C --> G[Scheduler]
```

### Components

<Tabs>
    <Tab title="Frontend">
        The Nuxt frontend service: - Server-Side Rendered application - Built
        with Vue 3 and Tailwind CSS - Handles dynamic rendering and client-side
        interactivity - Optimized for production performance
    </Tab>
    <Tab title="Backend">
        The Laravel API service: - Handles business logic and data persistence -
        Provides REST API endpoints - Manages file uploads and processing -
        Includes required PHP extensions (pgsql, redis, etc.) - Configured for
        PostgreSQL and Redis connections
    </Tab>
    <Tab title="Workers">
        Background processing services: - **API Worker**: Processes queued jobs
        (emails, exports, etc.) - **API Scheduler**: Handles scheduled tasks and
        periodic cleanups - Both share the same codebase as the main API
    </Tab>
    <Tab title="Databases">
        Data storage services: - **PostgreSQL**: Primary database for all
        application data - **Redis**: Used for: - Session storage - Cache -
        Queue management - Real-time features
    </Tab>
    <Tab title="Proxy">
        The Nginx proxy service: - Routes requests between frontend and backend
        - Handles SSL termination - Manages file upload limits - Serves static
        assets - Configured for optimal performance
    </Tab>
</Tabs>

## Docker Images

OpnForm provides pre-built Docker images for easy deployment:

-   [OpnForm API Image](https://hub.docker.com/r/jhumanj/opnform-api)
-   [OpnForm Client Image](https://hub.docker.com/r/jhumanj/opnform-client)

### Building Custom Images

While we recommend using the official images, you can build custom images if needed:

```bash
# Build all images
docker compose build

# Or build specific images
docker build -t opnform-api:local -f docker/Dockerfile.api .
docker build -t opnform-ui:local -f docker/Dockerfile.client .
```

### Custom Configuration

Create a `docker-compose.override.yml` to customize your deployment:

```yaml
services:
    api:
        image: opnform-api:local
        environment:
            PHP_MEMORY_LIMIT: 1G
    ui:
        image: opnform-ui:local
    ingress:
        volumes:
            - ./custom-nginx.conf:/etc/nginx/conf.d/default.conf
```

## Environment Variables

For detailed information about environment variables and how to update them in Docker, see our [Environment Variables](/configuration/environment-variables#docker-environment-variables) documentation.

## Maintenance

### Updates

1. Pull latest changes:

    ```bash
    git pull origin main
    ```

2. Update containers:
    ```bash
    docker compose pull
    docker compose up -d
    ```

### Monitoring

View container logs:

```bash
# All containers
docker compose logs -f

# Specific container
docker compose logs -f api
```

Monitor container health:

```bash
docker compose ps
```

## Troubleshooting

### Container Issues

If containers aren't starting:

```bash
# View detailed logs
docker compose logs -f

# Recreate containers
docker compose down
docker compose up -d
```

### Database Issues

If database connections fail:

```bash
# Check database status
docker compose exec db pg_isready

# View database logs
docker compose logs db
```

If the API container is stuck on "Waiting for DB to be ready":

```bash
# Check for line ending issues in the artisan script
# The file should use LF (Unix) line endings, not CRLF (Windows)

# Fix line endings on Unix/Mac:
sed -i 's/\r$//' api/artisan

# Fix line endings on Windows (using Git Bash or WSL):
dos2unix api/artisan
```

<Note>
    **Line Ending Issue**: When using Git or code editors on Windows, line
    endings in the `artisan` script may be converted from LF (Unix-style) to
    CRLF (Windows-style). This prevents the Docker container from properly
    executing the script, causing it to hang at "Waiting for DB to be ready".
    Always ensure script files maintain LF line endings.
</Note>

### Cache Issues

Clear various caches:

```bash
# Clear application cache
docker compose exec api php artisan cache:clear

# Clear config cache
docker compose exec api php artisan config:clear

# Clear route cache
docker compose exec api php artisan route:clear
```

### Permission Issues

Fix storage permissions:

```bash
docker compose exec api chown -R www-data:www-data storage
docker compose exec api chmod -R 775 storage
```