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

# Docker Deployment

> Deploy Activepieces using a single Docker container

The quickest way to get Activepieces running is using a single Docker container. This is ideal for development, testing, or small-scale production deployments.

<Warning>
  For production deployments with multiple workflows, we recommend using [Docker Compose](/deployment/docker-compose) or [Kubernetes](/deployment/kubernetes) for better scalability and separation of concerns.
</Warning>

## Quick Start

Deploy Activepieces with a single command:

```bash theme={null}
docker run -d \
  --name activepieces \
  -p 8080:80 \
  -e AP_POSTGRES_DATABASE=activepieces \
  -e AP_POSTGRES_HOST=postgres \
  -e AP_POSTGRES_PORT=5432 \
  -e AP_POSTGRES_USERNAME=postgres \
  -e AP_POSTGRES_PASSWORD=your_secure_password \
  -e AP_REDIS_HOST=redis \
  -e AP_REDIS_PORT=6379 \
  -e AP_FRONTEND_URL=http://localhost:8080 \
  -e AP_ENCRYPTION_KEY=$(openssl rand -hex 32) \
  -e AP_JWT_SECRET=$(openssl rand -hex 32) \
  -v activepieces_cache:/usr/src/app/cache \
  ghcr.io/activepieces/activepieces:0.79.0
```

<Info>
  This command requires separate PostgreSQL and Redis containers. For an all-in-one solution, use [Docker Compose](/deployment/docker-compose).
</Info>

## Understanding the Docker Image

### Image Details

* **Registry**: GitHub Container Registry (ghcr.io)
* **Repository**: `ghcr.io/activepieces/activepieces`
* **Base Image**: `node:20.19-bullseye-slim`
* **Architecture**: Multi-stage build for optimized size

### What's Included

<Steps>
  <Step title="System Dependencies">
    The image includes essential system packages:

    * **Python 3**: For native module compilation
    * **Build tools**: g++, make, git
    * **PDF support**: poppler-utils for PDF processing
    * **Bun**: Fast package manager (v1.3.1)
    * **PM2**: Process manager for scaling
  </Step>

  <Step title="Runtime Components">
    Application components:

    * **API Server**: Backend application (Node.js + Fastify)
    * **Frontend**: Angular web app served by Nginx
    * **Engine**: Workflow execution engine
    * **isolated-vm**: Sandboxing library for secure code execution
  </Step>

  <Step title="Configuration">
    * **Nginx**: Serves frontend on port 80
    * **Entrypoint**: Custom script for environment setup
    * **Volume**: `/usr/src/app/cache` for temporary files
  </Step>
</Steps>

## Dockerfile Breakdown

Here's how the Activepieces image is built:

### Stage 1: Base Image

```dockerfile theme={null}
FROM node:20.19-bullseye-slim AS base

# Install system dependencies
RUN apt-get update && \
    apt-get install -y --no-install-recommends \
        openssh-client \
        python3 \
        g++ \
        build-essential \
        git \
        poppler-utils \
        poppler-data \
        procps \
        locales \
        unzip \
        curl \
        ca-certificates \
        libcap-dev

# Install Bun package manager
RUN export ARCH=$(uname -m) && \
    if [ "$ARCH" = "x86_64" ]; then \
      curl -fSL https://github.com/oven-sh/bun/releases/download/bun-v1.3.1/bun-linux-x64-baseline.zip -o bun.zip; \
    elif [ "$ARCH" = "aarch64" ]; then \
      curl -fSL https://github.com/oven-sh/bun/releases/download/bun-v1.3.1/bun-linux-aarch64.zip -o bun.zip; \
    fi && \
    unzip bun.zip && \
    mv bun-*/bun /usr/local/bin/bun && \
    chmod +x /usr/local/bin/bun

# Install global Node packages
RUN npm install -g --no-fund --no-audit \
    node-gyp \
    npm@9.9.3 \
    pm2@6.0.10 \
    typescript@4.9.4

# Install isolated-vm for sandboxing
RUN cd /usr/src && bun install isolated-vm@5.0.1
```

### Stage 2: Build

```dockerfile theme={null}
FROM base AS build

WORKDIR /usr/src/app

# Install dependencies
COPY .npmrc package.json bun.lock bunfig.toml ./
COPY packages/ ./packages/
RUN bun install --frozen-lockfile

# Build application
COPY . .
RUN npx turbo run build --filter=web --filter=@activepieces/engine --filter=api
```

### Stage 3: Runtime

```dockerfile theme={null}
FROM base AS run

WORKDIR /usr/src/app

# Install Nginx for serving frontend
RUN apt-get update && \
    apt-get install -y --no-install-recommends nginx gettext

# Copy nginx configuration
COPY nginx.react.conf /etc/nginx/nginx.conf

# Copy built application
COPY --from=build /usr/src/app/dist/packages/engine/ ./dist/packages/engine/
COPY --from=build /usr/src/app/dist/packages/web /usr/share/nginx/html/

# Copy entrypoint script
COPY docker-entrypoint.sh .
RUN chmod +x docker-entrypoint.sh

ENTRYPOINT ["./docker-entrypoint.sh"]
EXPOSE 80
```

## Entrypoint Script

The container uses a custom entrypoint script that:

<CodeGroup>
  ```bash docker-entrypoint.sh theme={null}
  #!/bin/sh

  # Set default values if not provided
  export AP_APP_TITLE="${AP_APP_TITLE:-Activepieces}"
  export AP_FAVICON_URL="${AP_FAVICON_URL:-https://cdn.activepieces.com/brand/favicon.ico}"

  # Process environment variables in index.html
  envsubst '${AP_APP_TITLE} ${AP_FAVICON_URL}' < /usr/share/nginx/html/index.html > /usr/share/nginx/html/index.html.tmp && \
  mv /usr/share/nginx/html/index.html.tmp /usr/share/nginx/html/index.html

  # Start Nginx server
  nginx -g "daemon off;" &

  # Start backend server
  if [ "$AP_CONTAINER_TYPE" = "APP" ] && [ "$AP_PM2_ENABLED" = "true" ]; then
      echo "Starting backend server with PM2 (APP mode)"
      pm2-runtime start packages/server/api/dist/src/bootstrap.js --name "activepieces-app" --node-args="--enable-source-maps" -i 0
  else
      echo "Starting backend server with Node.js (WORKER mode or default)"
      node --enable-source-maps packages/server/api/dist/src/bootstrap.js
  fi
  ```
</CodeGroup>

## Port Configuration

The container exposes port 80 internally, which you map to your host:

<Tabs>
  <Tab title="Port 8080 (Default)">
    ```bash theme={null}
    docker run -p 8080:80 ghcr.io/activepieces/activepieces:0.79.0
    ```

    Access at: [http://localhost:8080](http://localhost:8080)
  </Tab>

  <Tab title="Port 80 (HTTP)">
    ```bash theme={null}
    docker run -p 80:80 ghcr.io/activepieces/activepieces:0.79.0
    ```

    Access at: [http://localhost](http://localhost)
  </Tab>

  <Tab title="Custom Port">
    ```bash theme={null}
    docker run -p 3000:80 ghcr.io/activepieces/activepieces:0.79.0
    ```

    Access at: [http://localhost:3000](http://localhost:3000)
  </Tab>
</Tabs>

## Volume Mounts

Mount volumes to persist data:

```bash theme={null}
docker run -d \
  -v activepieces_cache:/usr/src/app/cache \
  ghcr.io/activepieces/activepieces:0.79.0
```

<Info>
  The `/usr/src/app/cache` directory stores temporary files during workflow execution. This should be persisted to avoid data loss.
</Info>

## Environment Variables

See the [Environment Variables](/deployment/environment-variables) page for a complete list of configuration options.

Minimum required variables:

```bash theme={null}
# Database
AP_POSTGRES_DATABASE=activepieces
AP_POSTGRES_HOST=postgres
AP_POSTGRES_USERNAME=postgres
AP_POSTGRES_PASSWORD=your_password

# Redis
AP_REDIS_HOST=redis
AP_REDIS_PORT=6379

# Security
AP_ENCRYPTION_KEY=your_32_char_hex_key
AP_JWT_SECRET=your_jwt_secret

# Application
AP_FRONTEND_URL=http://localhost:8080
```

## Using Environment Files

Create a `.env` file and use it with Docker:

```bash theme={null}
docker run -d \
  --name activepieces \
  -p 8080:80 \
  --env-file .env \
  -v activepieces_cache:/usr/src/app/cache \
  ghcr.io/activepieces/activepieces:0.79.0
```

## Health Checks

Add health checks to your container:

```bash theme={null}
docker run -d \
  --name activepieces \
  --health-cmd="curl -f http://localhost:80/v1/health || exit 1" \
  --health-interval=30s \
  --health-timeout=10s \
  --health-retries=3 \
  -p 8080:80 \
  ghcr.io/activepieces/activepieces:0.79.0
```

Check container health:

```bash theme={null}
docker ps --format "table {{.Names}}\t{{.Status}}"
```

## Container Management

<Tabs>
  <Tab title="Start/Stop">
    ```bash theme={null}
    # Start container
    docker start activepieces

    # Stop container
    docker stop activepieces

    # Restart container
    docker restart activepieces
    ```
  </Tab>

  <Tab title="Logs">
    ```bash theme={null}
    # View logs
    docker logs activepieces

    # Follow logs
    docker logs -f activepieces

    # Last 100 lines
    docker logs --tail 100 activepieces
    ```
  </Tab>

  <Tab title="Shell Access">
    ```bash theme={null}
    # Interactive shell
    docker exec -it activepieces /bin/bash

    # Run command
    docker exec activepieces node --version
    ```
  </Tab>
</Tabs>

## Updating Activepieces

<Steps>
  <Step title="Pull latest image">
    ```bash theme={null}
    docker pull ghcr.io/activepieces/activepieces:latest
    ```
  </Step>

  <Step title="Stop current container">
    ```bash theme={null}
    docker stop activepieces
    docker rm activepieces
    ```
  </Step>

  <Step title="Start new container">
    ```bash theme={null}
    docker run -d \
      --name activepieces \
      -p 8080:80 \
      --env-file .env \
      -v activepieces_cache:/usr/src/app/cache \
      ghcr.io/activepieces/activepieces:latest
    ```
  </Step>
</Steps>

<Warning>
  Always backup your database before updating to a new version.
</Warning>

## Troubleshooting

<AccordionGroup>
  <Accordion title="Container won't start">
    Check logs for errors:

    ```bash theme={null}
    docker logs activepieces
    ```

    Common issues:

    * Missing required environment variables
    * Cannot connect to PostgreSQL or Redis
    * Port already in use
  </Accordion>

  <Accordion title="Cannot access on port 8080">
    Verify port mapping:

    ```bash theme={null}
    docker port activepieces
    ```

    Check if Nginx is running:

    ```bash theme={null}
    docker exec activepieces ps aux | grep nginx
    ```
  </Accordion>

  <Accordion title="High memory usage">
    Check container stats:

    ```bash theme={null}
    docker stats activepieces
    ```

    Consider limiting memory:

    ```bash theme={null}
    docker run --memory=4g ghcr.io/activepieces/activepieces:0.79.0
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Configure Environment" icon="gear" href="/deployment/environment-variables">
    Learn about all configuration options
  </Card>

  <Card title="Setup Database" icon="database" href="/deployment/database">
    Configure PostgreSQL for production
  </Card>

  <Card title="Docker Compose" icon="layer-group" href="/deployment/docker-compose">
    Upgrade to multi-container setup
  </Card>

  <Card title="Scaling" icon="chart-line" href="/deployment/scaling">
    Scale your deployment
  </Card>
</CardGroup>