export const metadata = {
  title: "Guide to Deploying Formbricks Using Docker",
  description:
    "Step-by-step tutorial on how to effortlessly set up and run Formbricks via Docker. Explore the quick deployment process with Docker-Compose, learn how to update Formbricks, and troubleshoot common issues. Ideal for those looking for a hassle-free Formbricks experience",
};

#### Self-Hosting

# Advanced Setup

Quickly set up and start using Formbricks with our [official Docker image](https://github.com/formbricks/formbricks/pkgs/container/formbricks) that we've already built for you.

The pre-built image is ready-to-run, and it only requires minimal configuration on your part. It's as easy as downloading the Docker image and firing up the container.

### Requirements

Ensure `docker` & `docker compose` are installed on your server/system. Both are typically included with Docker utilities, like Docker Desktop and Rancher Desktop.

<Note>
  `docker compose` without the hyphen is now the primary method of using docker-compose, according to the
  Docker documentation.
</Note>

## Start

1.  **Create a New Directory for Formbricks**

Open a terminal and create a new directory for Formbricks, then navigate into this new directory:

<Col>
   <CodeGroup title="Create and cd into the new directory">

    ```bash
    mkdir formbricks-quickstart && cd formbricks-quickstart
    ```

    </CodeGroup>

</Col>

2.  **Download the Docker-Compose File**

Download the docker-compose file directly from the Formbricks repository:

<Col>
   <CodeGroup title="Download docker compose file">

    ```bash
    curl -o docker-compose.yml https://raw.githubusercontent.com/formbricks/formbricks/main/docker/docker-compose.yml
    ```

    </CodeGroup>

</Col>

3.  **Generate NextAuth Secret**

Next, you need to generate a NextAuth secret. This will be used for session signing and encryption. The `sed` command below generates a random string using `openssl`, then replaces the `NEXTAUTH_SECRET:` placeholder in the `docker-compose.yml` file with this generated secret:

<Col>
   <CodeGroup title="Generate NextAuth Secret">

    ```bash
    sed -i "/NEXTAUTH_SECRET:$/s/NEXTAUTH_SECRET:.*/NEXTAUTH_SECRET: $(openssl rand -hex 32)/" docker-compose.yml
    ```

    </CodeGroup>

</Col>

4.  **Generate Encryption Key**

Next, you need to generate an Encryption Key. This will be used for authenticating and verifying 2 Factor Authentication. The `sed` command below generates a random string using `openssl`, then replaces the `ENCRYPTION_KEY:` placeholder in the `docker-compose.yml` file with this generated secret:

<Col>
   <CodeGroup title="Generate Encryption Key">

    ```bash
    sed -i "/ENCRYPTION_KEY:$/s/ENCRYPTION_KEY:.*/ENCRYPTION_KEY: $(openssl rand -hex 32)/" docker-compose.yml
    ```

    </CodeGroup>

</Col>

5.  **Generate Cron Secret**

Next, you need to generate a Cron secret. This will be used as an API Secret for running cron jobs. The `sed` command below generates a random string using `openssl`, then replaces the `CRON_SECRET:` placeholder in the `docker-compose.yml` file with this generated secret:

<Col>
   <CodeGroup title="Generate Cron Secret">

    ```bash
    sed -i "/CRON_SECRET:$/s/CRON_SECRET:.*/CRON_SECRET: $(openssl rand -hex 32)/" docker-compose.yml
    ```

    </CodeGroup>

</Col>

6.  **Start the Docker Setup**

You're now ready to start the Formbricks Docker setup. The following command will start Formbricks together with a postgreSQL database using Docker Compose:

<Col>
   <CodeGroup title="Launch Docker Instance">

```bash
 docker compose up -d
```

   </CodeGroup>
</Col>
   The `-d` flag will run the containers in detached mode, meaning they'll run in the background.

7. **Visit Formbricks in Your Browser**

   After starting the Docker setup, visit http://localhost:3000 in your browser to interact with the Formbricks application. The first time you access this page, you'll be greeted by a setup wizard. Follow the prompts to define your first user and get started.

## Update

<Note>
  Please take a look at our [migration guide](/self-hosting/migration-guide) for version specific steps to
  update Formbricks.
</Note>

1.  Pull the latest Formbricks image

<Col>
   <CodeGroup title="Pull the changes into docker">

    ```bash
    docker compose pull
    ```

    </CodeGroup>

</Col>

2.  Stop the Formbricks stack

<Col>
   <CodeGroup title="Stop the docker instance">

    ```bash
    docker compose down
    ```

    </CodeGroup>

</Col>

3.  Re-start the Formbricks stack with the updated image

<Col>
   <CodeGroup title="Relaunch the Docker Instance">

    ```bash
    docker compose up -d
    ```

    </CodeGroup>

</Col>

## Debug

If you encounter any issues, you can check the logs of the container with:

<Col>
<CodeGroup title="Look into docker logs">

```bash
docker compose logs -f
```

</CodeGroup>
</Col>
In an ideal case, you should see something like this:
<Col>
<CodeGroup title="Docker Build Underway">

```bash
[+] Running 9/16
⠹ formbricks 15 layers [⣿⣤⣿⣿⣿⣿⣿⣿⣿⣿⠀⠀⠀⠀⠀] 29.78MB/47.76MB Pulling                                                           13.3s
✔ 7264a8db6415 Already exists                                                                                                 0.0s
⠋ 751194035c36 Downloading    [===============================>                   ]  29.78MB/47.76...                         8.1s
✔ eff5dce73b38 Download complete                                                                                              1.7s
✔ c8ce5be43019 Download complete                                                                                              1.2s
✔ a2f33c630af5 Download complete                                                                                              5.1s
✔ e3b64e437860 Download complete                                                                                              3.3s
✔ a6551ac5f976 Download complete                                                                                              4.9s
✔ 4f4fb700ef54 Download complete                                                                                              6.0s
✔ 22163889e16b Download complete                                                                                              6.7s
✔ dc647bb9eb13 Download complete                                                                                              7.8s
⠋ 49c2ad494720 Waiting                                                                                                        8.1s
⠋ 5c797a842dcb Waiting                                                                                                        8.1s
⠋ 1f231213db04 Waiting                                                                                                        8.1s
⠋ e407294bdcda Waiting                                                                                                        8.1s
⠋ 6fd8358dca47 Pulling fs layer                                                                                               8.1s

[+] Running 2/2
✔ Container formbricks-quickstart-postgres-1    Created                                                                       0.0s
✔ Container formbricks-quickstart-formbricks-1  Created                                                                       0.0s
```

</CodeGroup>
</Col>
And at the tail of the output, you should see something like this:
<Col>
<CodeGroup title="Docker Build Completed">

```bash
formbricks-quickstart-formbricks-1  | All migrations have been successfully applied.
formbricks-quickstart-formbricks-1  |
formbricks-quickstart-formbricks-1  | - info Loaded env from /home/nextjs/apps/web/.env
formbricks-quickstart-formbricks-1  | Listening on port 3000 url: http://<random-string>:3000
```

</CodeGroup>
</Col>
You can close the logs again with `CTRL + C`.

<Note>
## Customizing environment variables

To edit any of the available environment variables, check out our [Configure](/self-hosting/configuration) section!

</Note>

Still facing issues? [Join our Discord!](https://formbricks.com/discord) and we'd be glad to assist you!
