> ## Documentation Index
> Fetch the complete documentation index at: https://docs.opnform.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Docker Deployment

> Deploy OpnForm using Docker

<Note>
  The easiest way to get started with OpnForm is through our [official managed service in the Cloud](https://opnform.com/?utm_source=docs\&utm_medium=introduction\&utm_campaign=cloud_version). It takes just 1 minute to start building forms with the free plan, with high availability, backups, security, and maintenance all managed for you.
</Note>

<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 theme={null}
   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 theme={null}
   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 theme={null}
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 theme={null}
# 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 theme={null}
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 theme={null}
   git pull origin main
   ```

2. Update containers:
   ```bash theme={null}
   docker compose pull
   docker compose up -d
   ```

### Monitoring

View container logs:

```bash theme={null}
# All containers
docker compose logs -f

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

Monitor container health:

```bash theme={null}
docker compose ps
```

## Troubleshooting

### Container Issues

If containers aren't starting:

```bash theme={null}
# View detailed logs
docker compose logs -f

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

### Database Issues

If database connections fail:

```bash theme={null}
# 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 theme={null}
# 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 theme={null}
# 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 theme={null}
docker compose exec api chown -R www-data:www-data storage
docker compose exec api chmod -R 775 storage
```