mirror of
https://github.com/andwati/zitadel.git
synced 2026-10-19 22:14:25 +00:00
91 lines
4.3 KiB
Plaintext
91 lines
4.3 KiB
Plaintext
---
|
|
title: Set up Zitadel with Docker Compose
|
|
description: "Deploy a ZITADEL instance locally using Docker Compose for rapid testing and development."
|
|
sidebar_label: Docker Compose
|
|
---
|
|
|
|
import NoteInstanceNotFound from './troubleshooting/_note_instance_not_found.mdx';
|
|
import DockerCompose from './docker-compose.yaml';
|
|
import { DynamicCodeBlock } from 'fumadocs-ui/components/dynamic-codeblock';
|
|
|
|
import Disclaimer from './_disclaimer.mdx'
|
|
import DefaultUser from './_defaultuser.mdx'
|
|
import Next from './_next.mdx'
|
|
|
|
This guide is the entrypoint for running the Zitadel platform locally for the first time.
|
|
It is for demonstration and development purposes only and does not set up a production-ready and security hardened instance of Zitadel.
|
|
Once Zitadel up is and running, learn more about a production setup in the [What's Next section](#next-steps).
|
|
|
|
## Prerequisites
|
|
|
|
The setup is likely to work with other software versions too, but it is tested against the following environment:
|
|
|
|
- Ubuntu 24.04.1
|
|
- Docker 28.3.2
|
|
- Docker Compose v2.38.2
|
|
- curl 8.5.0
|
|
|
|
## Docker compose
|
|
|
|
The following commands set up services for a PostgreSQL database, a Zitadel API and a Zitadel login:
|
|
|
|
1. Download the `docker-compose.yaml` file from the Zitadel repository:
|
|
```shell
|
|
curl -L https://raw.githubusercontent.com/zitadel/zitadel/main/apps/docs/content/self-hosting/deploy/docker-compose.yaml -o docker-compose.yaml
|
|
```
|
|
2. Make sure the containers use the latest image versions.
|
|
```shell
|
|
docker compose pull
|
|
```
|
|
3. Run the PostgreSQL database, the Zitadel API, and the Zitadel login.
|
|
```shell
|
|
docker compose up --detach --wait
|
|
```
|
|
4. Verify the containers are running and healthy.
|
|
```shell
|
|
docker compose ps
|
|
```
|
|
|
|
<DefaultUser components={props.components} />
|
|
|
|
## What's next
|
|
|
|
Before proceeding, review the downloaded `docker-compose.yaml` file:
|
|
The comments give context to the used variables and show examples for commonly used configuration variants.
|
|
|
|
<details>
|
|
<summary>docker-compose.yaml</summary>
|
|
<DynamicCodeBlock lang="yaml" code={DockerCompose} />
|
|
</details>
|
|
|
|
Here are some natural steps forward to go from the current setup to production:
|
|
|
|
- **Use a different master key**: Set up an instance from scratch and use a different master key. For example, generate one by running `tr -dc A-Za-z0-9 </dev/urandom | head -c 32`
|
|
- **Use files for secrets instead of environment variables, and don't commit them to Git**: Learn how to [configure the platform](/self-hosting/manage/configure)
|
|
- **Run the containers as non-root users**: Remove the `user: "0"` lines from the `docker-compose.yaml` file.
|
|
- **Configure a different external domain or IP**: Beware that the login only works with HTTPS on non-localhost domains. [Run and configure a reverse proxy](/self-hosting/manage/reverseproxy/reverse_proxy)
|
|
- **Serve the API and the UI together on the same port**: [Run and configure a reverse proxy](/self-hosting/manage/reverseproxy/reverse_proxy)
|
|
- **Encrypt Traffic**: [Run and configure a reverse proxy](/self-hosting/manage/reverseproxy/reverse_proxy)
|
|
|
|
For more detailed recommendations, read the [Zitadel Production Setup Guide](/self-hosting/manage/production).
|
|
|
|
<details>
|
|
<summary>Read this if the environment uses the login v1</summary>
|
|
<p>
|
|
The login v2 is the next generation of the Zitadel login.
|
|
Its code and deployment are easily customizable.
|
|
Unlike the login v1, it runs in its own process.
|
|
The login v2 is enabled by default in new installations.
|
|
But if an existing `docker-compose.yaml` file is updated by following this guide,
|
|
an additional `zitadel-login` service is now running which is actually not doing anything, yet.
|
|
The following steps give guidance on how to enable the login v2 in an environment.
|
|
</p>
|
|
<ol>
|
|
<li>Read the login v2 related comments in the docker-compose.yaml.</li>
|
|
<li><a href="../../self-hosting/manage/login-client#create-login-client">Manually create a login client personal access token (PAT) for the now running v2 login</a>.</li>
|
|
<li>Move the PAT to `./login-client.pat`</li>
|
|
<li>Restart the login process: `docker compose restart login`</li>
|
|
<li><a href="../../self-hosting/manage/login-client#require-login-v2">Enable the Login UI for all users</a></li>
|
|
</ol>
|
|
</details>
|