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

# Installation

> Full installation walkthrough for production CertForge Self-Hosted deployments.

## Download

Download the binary for your platform from the [releases page](https://github.com/certforge/self-hosted/releases/latest).

| Platform      | Filename                      |
| ------------- | ----------------------------- |
| Linux amd64   | `certforge-linux-amd64`       |
| Linux arm64   | `certforge-linux-arm64`       |
| macOS amd64   | `certforge-darwin-amd64`      |
| macOS arm64   | `certforge-darwin-arm64`      |
| Windows amd64 | `certforge-windows-amd64.exe` |

```bash theme={null}
# Linux amd64
sudo curl -Lo /usr/local/bin/certforge \
  https://github.com/certforge/self-hosted/releases/latest/download/certforge-linux-amd64
sudo chmod +x /usr/local/bin/certforge
certforge --version
```

***

## Create a dedicated user

Running as root is not recommended. Create a system user:

```bash theme={null}
sudo useradd --system --no-create-home --shell /usr/sbin/nologin certforge
```

***

## Set up directories

```bash theme={null}
# Application data — persistent across upgrades
sudo mkdir -p /opt/certforge/data

# Config
sudo mkdir -p /etc/certforge

# Logs (optional — systemd journal is preferred)
sudo mkdir -p /var/log/certforge

# Set ownership
sudo chown -R certforge:certforge /opt/certforge /var/log/certforge
sudo chmod 750 /opt/certforge/data
```

***

## Install the license file

```bash theme={null}
sudo cp license.jwt /opt/certforge/data/license.jwt
sudo chown certforge:certforge /opt/certforge/data/license.jwt
sudo chmod 640 /opt/certforge/data/license.jwt
```

***

## Configuration file

Create `/etc/certforge/config.yaml`:

```yaml theme={null}
mode: self-hosted

server:
  listen_address: 0.0.0.0
  dashboard_port: 8080
  port: 8443
  dashboard_enabled: true
  read_timeout: 30s
  write_timeout: 30s
  # Restrict dashboard to specific networks (recommended for production)
  allowed_cidrs:
    - 10.0.0.0/8
    - 192.168.0.0/16

storage:
  base_path: /opt/certforge/data

# Optional: PostgreSQL for multi-org or HA deployments
# database:
#   url: postgres://certforge:password@localhost:5432/certforge?sslmode=require

# ACME CA providers are configured via the admin dashboard (Admin → Certificate Authorities).

# TLS for the dashboard (optional — use a reverse proxy instead if preferred)
# server_tls:
#   domains:
#     - certforge.internal
#   ca_id: internal-ca
```

Set permissions:

```bash theme={null}
sudo chown root:certforge /etc/certforge/config.yaml
sudo chmod 640 /etc/certforge/config.yaml
```

***

## Install as a systemd service

See [Running as a systemd Service](/self-hosted/systemd) for the full unit file.

***

## Firewall

Open the required ports:

```bash theme={null}
# Dashboard
sudo ufw allow 8080/tcp comment "CertForge dashboard"

# mTLS ACME API (restrict to internal networks)
sudo ufw allow from 10.0.0.0/8 to any port 8443 proto tcp comment "CertForge ACME API"
sudo ufw allow from 192.168.0.0/16 to any port 8443 proto tcp comment "CertForge ACME API"

# HTTP-01 ACME validation (only if using HTTP-01)
# sudo ufw allow 80/tcp comment "ACME HTTP-01"
```

***

## First launch

```bash theme={null}
# Start via systemd
sudo systemctl start certforge
sudo systemctl status certforge

# Or run directly for testing
certforge --config /etc/certforge/config.yaml
```

Open the dashboard at `https://your-server:8080`. You will be prompted to create the initial superuser account on the first visit.

<Note>
  The server generates a self-signed TLS certificate on first run. Your browser will show a security warning — click **Advanced → Proceed** to continue. To permanently trust the certificate, import `./data/cas/internal-ca.crt` (or `/var/lib/certforge/cas/internal-ca.crt`) into your browser or OS certificate store.
</Note>

***

## Verify the installation

```bash theme={null}
# Check the process is running
systemctl is-active certforge

# Check license status
curl -sk https://localhost:8080/api/license | jq .

# Check ACME directory is reachable
curl -sk https://localhost:8443/acme/directory | jq .meta
```

***

## PostgreSQL setup (optional)

If you need PostgreSQL:

```bash theme={null}
# Create the database and user
psql -U postgres << 'SQL'
CREATE USER certforge WITH PASSWORD 'strong-password-here';
CREATE DATABASE certforge OWNER certforge;
GRANT ALL PRIVILEGES ON DATABASE certforge TO certforge;
SQL
```

Add to your config:

```yaml theme={null}
database:
  url: postgres://certforge:strong-password-here@localhost:5432/certforge?sslmode=require
```

CertForge runs schema migrations automatically on startup — no manual `CREATE TABLE` needed.