> ## Documentation Index
> Fetch the complete documentation index at: https://infisical.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Docker Compose
> Deploy Infisical using Docker Compose for development, testing, or small-scale production environments.
Learn how to deploy **Infisical** using Docker Compose. This method runs Infisical and its dependencies (PostgreSQL and Redis) as containers on a single Docker host. It's ideal for trying out Infisical, development environments, or small-scale deployments that don't require high availability.
The short video below walks through deploying Infisical with Docker Compose, covering each step from setup to a running instance.
## Prerequisites
* A Linux server (Ubuntu 20.04+ recommended) or macOS/Windows with Docker Desktop
* [Docker Engine](https://docs.docker.com/engine/install/) (version 20.10+)
* [Docker Compose](https://docs.docker.com/compose/install/) (version 2.0+ recommended)
This Docker Compose configuration is not designed for high-availability production scenarios.
It includes just the essential components needed to set up an Infisical proof of concept (POC).
To run Infisical in a highly available manner, see the [Kubernetes guide](/self-hosting/deployment-options/kubernetes-helm).
## System Requirements
The following are minimum requirements for running Infisical with Docker Compose:
| Component | Minimum | Recommended |
| --------- | ------- | ------------------------ |
| CPU | 2 cores | 4 cores |
| RAM | 4 GB | 8 GB |
| Disk | 20 GB | 50 GB+ (SSD recommended) |
These requirements include resources for Infisical, PostgreSQL, and Redis containers. For larger deployments with many secrets or users, increase resources accordingly.
## Deployment Steps
Confirm that Docker and Docker Compose are installed on your machine:
```bash theme={"dark"}
docker --version
docker compose version
```
You should see version information for both commands. If not, install Docker and Docker Compose following the official documentation.
You can obtain the Infisical docker compose file by using a command-line downloader such as `wget` or `curl`. If your system doesn't have either of these, you can use an equivalent command that works with your machine.
```bash theme={"dark"}
curl -o docker-compose.prod.yml https://raw.githubusercontent.com/Infisical/infisical/main/docker-compose.prod.yml
```
```bash theme={"dark"}
wget -O docker-compose.prod.yml https://raw.githubusercontent.com/Infisical/infisical/main/docker-compose.prod.yml
```
Infisical requires a set of credentials used for connecting to dependent services such as Postgres, Redis, etc. The default credentials can be downloaded using one of the commands listed below.
```bash theme={"dark"}
curl -o .env https://raw.githubusercontent.com/Infisical/infisical/main/.env.example
```
```bash theme={"dark"}
wget -O .env https://raw.githubusercontent.com/Infisical/infisical/main/.env.example
```
Once downloaded, the credentials file will be saved to your working directory as `.env` file. View all available configurations [here](/self-hosting/configuration/envars).
The `.env` file contains secrets that control the security of your deployment. Do not commit it to version control, and protect access to it:
```bash theme={"dark"}
chmod 600 .env
```
Start all services in detached mode:
```bash theme={"dark"}
docker compose -f docker-compose.prod.yml up -d
```
This command starts three containers:
* **backend**: The main Infisical application (exposed on host port 80, internal port 8080)
* **db**: PostgreSQL database for storing encrypted secrets
* **redis**: Redis for caching and job queues
Check that all containers are running:
```bash theme={"dark"}
docker compose -f docker-compose.prod.yml ps
```
You should see all three services with a status of `Up`. Next, verify Infisical is responding:
```bash theme={"dark"}
curl -s http://localhost:80/api/status | head -c 100
```
If successful, open your browser and navigate to `http://localhost:80` (or your configured domain) to create your admin account.
The first user to sign up becomes the instance administrator. Make sure to complete this step before exposing Infisical to others.
Podman Compose is an alternative way to run Infisical using Podman as a replacement for Docker. Podman is backwards compatible with Docker Compose files.
Confirm that Podman and Podman Compose are installed:
```bash theme={"dark"}
podman version
podman-compose version
```
If not installed, follow the [Podman installation guide](https://podman-desktop.io/docs/installation) and [Podman Compose guide](https://podman-desktop.io/docs/compose).
You can obtain the Infisical docker compose file by using a command-line downloader such as `wget` or `curl`. If your system doesn't have either of these, you can use an equivalent command that works with your machine.
```bash theme={"dark"}
curl -o docker-compose.prod.yml https://raw.githubusercontent.com/Infisical/infisical/main/docker-compose.prod.yml
```
```bash theme={"dark"}
wget -O docker-compose.prod.yml https://raw.githubusercontent.com/Infisical/infisical/main/docker-compose.prod.yml
```
Infisical requires a set of credentials used for connecting to dependent services such as Postgres, Redis, etc. The default credentials can be downloaded using one of the commands listed below.
```bash theme={"dark"}
curl -o .env https://raw.githubusercontent.com/Infisical/infisical/main/.env.example
```
```bash theme={"dark"}
wget -O .env https://raw.githubusercontent.com/Infisical/infisical/main/.env.example
```
Once downloaded, the credentials file will be saved to your working directory as `.env` file. View all available configurations [here](/self-hosting/configuration/envars).
Initialize and start the Podman machine:
```bash theme={"dark"}
podman machine init --now
podman machine set --rootful
podman machine start
```
If using a rootless Podman install, you can skip `podman machine set --rootful`.
```bash theme={"dark"}
podman-compose -f docker-compose.prod.yml up -d
```
Access the UI at `http://localhost:80`.
***
## Managing Your Deployment
### Stopping and Restarting Services
To stop all Infisical services:
```bash theme={"dark"}
docker compose -f docker-compose.prod.yml down
```
To restart services:
```bash theme={"dark"}
docker compose -f docker-compose.prod.yml up -d
```
To restart a specific service (e.g., after configuration changes):
```bash theme={"dark"}
docker compose -f docker-compose.prod.yml restart backend
```
### Data Persistence and Volumes
The Docker Compose configuration uses named volumes to persist data:
| Volume | Purpose | Data Stored |
| ------------ | --------------- | --------------------------------------------------------- |
| `pg_data` | PostgreSQL data | All encrypted secrets, users, projects, and configuration |
| `redis_data` | Redis data | Cache and job queue data (can be regenerated) |
**Critical**: The `pg_data` volume contains all your encrypted secrets. Never delete this volume unless you intend to lose all data. Always back up before any maintenance operations.
To view volumes:
```bash theme={"dark"}
docker volume ls | grep -E "pg_data|redis_data"
```
To back up the PostgreSQL volume:
```bash theme={"dark"}
docker compose -f docker-compose.prod.yml exec db pg_dump -U infisical infisical > backup_$(date +%Y%m%d_%H%M%S).sql
```
### Viewing Logs
To view logs from all services:
```bash theme={"dark"}
docker compose -f docker-compose.prod.yml logs -f
```
To view logs from a specific service:
```bash theme={"dark"}
docker compose -f docker-compose.prod.yml logs -f backend
docker compose -f docker-compose.prod.yml logs -f db
docker compose -f docker-compose.prod.yml logs -f redis
```
To view the last 100 lines of logs:
```bash theme={"dark"}
docker compose -f docker-compose.prod.yml logs --tail=100 backend
```
Logs are also available directly from Docker:
```bash theme={"dark"}
docker logs --since 1h
```
***
## Additional Configuration
Configure your firewall to allow traffic to Infisical while securing other services:
**Required ports:**
| Port | Service | Access |
| ---- | -------------------- | ---------------------------- |
| 80 | HTTP (Infisical) | Public (or internal network) |
| 443 | HTTPS (if using TLS) | Public (or internal network) |
**Internal ports (should NOT be exposed publicly):**
| Port | Service | Notes |
| ---- | ---------- | --------------------------- |
| 5432 | PostgreSQL | Container-to-container only |
| 6379 | Redis | Container-to-container only |
**UFW (Ubuntu/Debian):**
```bash theme={"dark"}
# Allow HTTP/HTTPS
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
# Ensure database ports are not exposed
sudo ufw deny 5432/tcp
sudo ufw deny 6379/tcp
sudo ufw enable
```
**firewalld (RHEL/CentOS):**
```bash theme={"dark"}
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload
```
Never expose PostgreSQL (5432) or Redis (6379) ports to the public internet. These should only be accessible within the Docker network.
Infisical uses email for user invitations, password resets, and notifications. Configure SMTP by adding these variables to your `.env` file:
```env theme={"dark"}
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USERNAME=your-smtp-username
SMTP_PASSWORD=your-smtp-password
SMTP_FROM_ADDRESS=infisical@example.com
SMTP_FROM_NAME=Infisical
```
**Common SMTP providers:**
```env theme={"dark"}
SMTP_HOST=email-smtp.us-east-1.amazonaws.com
SMTP_PORT=587
SMTP_USERNAME=your-ses-smtp-username
SMTP_PASSWORD=your-ses-smtp-password
SMTP_FROM_ADDRESS=noreply@yourdomain.com
SMTP_FROM_NAME=Infisical
```
```env theme={"dark"}
SMTP_HOST=smtp.sendgrid.net
SMTP_PORT=587
SMTP_USERNAME=apikey
SMTP_PASSWORD=your-sendgrid-api-key
SMTP_FROM_ADDRESS=noreply@yourdomain.com
SMTP_FROM_NAME=Infisical
```
```env theme={"dark"}
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USERNAME=your-email@gmail.com
SMTP_PASSWORD=your-app-password
SMTP_FROM_ADDRESS=your-email@gmail.com
SMTP_FROM_NAME=Infisical
```
For Gmail, you must use an [App Password](https://support.google.com/accounts/answer/185833) instead of your regular password.
After updating the `.env` file, restart Infisical:
```bash theme={"dark"}
docker compose -f docker-compose.prod.yml restart backend
```
We recommend securing your Infisical deployment with HTTPS using a reverse proxy like NGINX.
**1. Obtain SSL certificates** (e.g., via Let's Encrypt):
```bash theme={"dark"}
sudo apt install certbot
sudo certbot certonly --standalone -d secrets.example.com
```
**2. Create NGINX configuration directory:**
```bash theme={"dark"}
mkdir -p ./nginx/certs
sudo cp /etc/letsencrypt/live/secrets.example.com/fullchain.pem ./nginx/certs/
sudo cp /etc/letsencrypt/live/secrets.example.com/privkey.pem ./nginx/certs/
```
**3. Add NGINX service to `docker-compose.prod.yml`:**
```yaml theme={"dark"}
nginx:
image: nginx:alpine
ports:
- "80:80"
- "443:443"
volumes:
- ./nginx/nginx.conf:/etc/nginx/nginx.conf:ro
- ./nginx/certs:/etc/nginx/certs:ro
depends_on:
- backend
```
**4. Create `./nginx/nginx.conf`:**
```nginx theme={"dark"}
events {}
http {
server {
listen 80;
server_name secrets.example.com;
return 301 https://$host$request_uri;
}
server {
listen 443 ssl;
server_name secrets.example.com;
ssl_certificate /etc/nginx/certs/fullchain.pem;
ssl_certificate_key /etc/nginx/certs/privkey.pem;
location / {
proxy_pass http://backend:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
}
```
**5. Update `.env`:**
```env theme={"dark"}
SITE_URL=https://secrets.example.com
```
**6. Restart services:**
```bash theme={"dark"}
docker compose -f docker-compose.prod.yml down
docker compose -f docker-compose.prod.yml up -d
```
For higher availability, use external managed services like AWS RDS and ElastiCache.
Update your `.env`:
```env theme={"dark"}
DB_CONNECTION_URI=postgresql://:@:5432/
REDIS_URL=redis://:@:6379
```
Remove or comment out `db` and `redis` services in `docker-compose.prod.yml`.
Ensure firewall/VPC access to these services is properly configured.
Regular backups are critical for protecting your data.
**Database backup:**
```bash theme={"dark"}
docker compose -f docker-compose.prod.yml exec db pg_dump -U infisical infisical > backup_$(date +%Y%m%d).sql
```
**Automated daily backups (cron):**
```bash theme={"dark"}
# Add to crontab (crontab -e)
0 2 * * * cd /path/to/infisical && docker compose -f docker-compose.prod.yml exec -T db pg_dump -U infisical infisical > /backups/infisical_$(date +\%Y\%m\%d).sql
```
**Restore from backup:**
```bash theme={"dark"}
docker compose -f docker-compose.prod.yml exec -T db psql -U infisical infisical < backup.sql
```
Also back up your `ENCRYPTION_KEY` from the `.env` file. Without this key, you cannot decrypt secrets even if you restore the database.
Infisical exposes Prometheus metrics when enabled.
**1. Add to `.env`:**
```env theme={"dark"}
OTEL_TELEMETRY_COLLECTION_ENABLED=true
OTEL_EXPORT_TYPE=prometheus
```
**2. Expose port `9464` in `docker-compose.prod.yml`** by adding to the backend service:
```yaml theme={"dark"}
ports:
- "80:8080"
- "9464:9464"
```
**3. Configure Prometheus** to scrape `localhost:9464` or the container DNS.
See the [Monitoring Guide](/self-hosting/guides/monitoring-telemetry) for full setup.
Keeping Infisical up-to-date ensures you receive the latest features and security patches.
**1. Back up your database:**
```bash theme={"dark"}
docker compose -f docker-compose.prod.yml exec db pg_dump -U infisical infisical > backup_before_upgrade.sql
```
**2. Update the image tag** in `docker-compose.prod.yml` to the desired version.
**3. Pull and restart:**
```bash theme={"dark"}
docker compose -f docker-compose.prod.yml pull
docker compose -f docker-compose.prod.yml up -d
```
**4. Verify the upgrade:**
```bash theme={"dark"}
docker compose -f docker-compose.prod.yml logs -f backend
```
Watch for successful database migration messages. See the [Upgrade Guide](/self-hosting/guides/upgrading-infisical) for more details.
***
## Troubleshooting
**Check container status:**
```bash theme={"dark"}
docker compose -f docker-compose.prod.yml ps -a
```
**View startup logs:**
```bash theme={"dark"}
docker compose -f docker-compose.prod.yml logs
```
**Common causes:**
* Port 80 already in use: Stop other services or change the port mapping
* Insufficient memory: Ensure at least 4GB RAM is available
* Invalid `.env` file: Check for syntax errors or missing required variables
**Check if PostgreSQL is running:**
```bash theme={"dark"}
docker compose -f docker-compose.prod.yml exec db pg_isready
```
**Verify database credentials:**
```bash theme={"dark"}
docker compose -f docker-compose.prod.yml exec db psql -U infisical -c "SELECT 1"
```
**Check Infisical logs for connection errors:**
```bash theme={"dark"}
docker compose -f docker-compose.prod.yml logs backend | grep -i "database\|postgres\|connection"
```
If the database was corrupted, you may need to restore from backup or recreate the volume:
```bash theme={"dark"}
docker compose -f docker-compose.prod.yml down -v # WARNING: Deletes all data
docker compose -f docker-compose.prod.yml up -d
```
**Verify the service is running:**
```bash theme={"dark"}
curl -v http://localhost:80/api/status
```
**Check if the port is listening:**
```bash theme={"dark"}
sudo netstat -tlnp | grep :80
# or
sudo ss -tlnp | grep :80
```
**Check firewall rules:**
```bash theme={"dark"}
sudo ufw status
# or
sudo firewall-cmd --list-all
```
**Verify SITE\_URL is correct** in your `.env` file and matches how you're accessing Infisical.
**Test SMTP connectivity:**
```bash theme={"dark"}
docker compose -f docker-compose.prod.yml exec backend nc -zv smtp.example.com 587
```
**Check Infisical logs for email errors:**
```bash theme={"dark"}
docker compose -f docker-compose.prod.yml logs backend | grep -i "smtp\|email\|mail"
```
**Common issues:**
* Incorrect SMTP credentials
* Firewall blocking outbound port 587 or 465
* SMTP provider requires specific authentication (e.g., Gmail App Passwords)
**Check resource usage:**
```bash theme={"dark"}
docker stats
```
**Check for slow database queries:**
```bash theme={"dark"}
docker compose -f docker-compose.prod.yml exec db psql -U infisical -c "SELECT * FROM pg_stat_activity WHERE state = 'active'"
```
**Solutions:**
* Increase container memory limits in `docker-compose.prod.yml`
* Add more CPU cores to the host
* Consider migrating to a managed database for better performance
If you have lost access to your admin account, you can reset it via the database:
```bash theme={"dark"}
# Connect to the database
docker compose -f docker-compose.prod.yml exec db psql -U infisical
# Find the user
SELECT id, email FROM users WHERE email = 'admin@example.com';
# The password must be reset through the application password reset flow
# or by deleting and recreating the user
```
For security reasons, passwords are hashed and cannot be directly reset in the database. Use the "Forgot Password" flow if SMTP is configured, or contact Infisical support for assistance.
***
Your Infisical instance should now be running on port `80` (or `443` if using TLS). Visit `http://localhost:80` or `https://` to access your instance.
