> For the complete documentation index, see [llms.txt](https://en.itmatic101.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://en.itmatic101.com/homelab/setting-up-step-ca-with-podman-for-my-homelab.md).

# Setting up step-ca with Podman for my homelab

If you run a homelab like I do, you probably have a few services that use HTTPS. Proxmox VE, internal dashboards, and reverse proxies are good examples.

The problem is that managing certificates individually can become annoying. Self-signed certificates work, but browser warnings get old pretty quickly.

So, I decided to set up my own Certificate Authority (CA) using [Smallstep step-ca](https://smallstep.com/docs/step-ca/) and Podman.

The idea is simple: create one internal CA that can issue certificates for services across my homelab. With ACME support, I can also automate certificate issuance and renewal for compatible services.

## 1. Run step-ca with Podman

First, pull the step-ca container image:

```bash
podman pull docker.io/smallstep/step-ca
```

Create a named volume to keep the CA data persistent:

```bash
podman volume create step-ca
```

Now initialise the CA:

```bash
podman run --rm -it \
  -v step-ca:/home/step \
  docker.io/smallstep/step-ca \
  step ca init
```

The setup wizard asks a few questions. For my lab, I used these values:

| Setting           | Value               |
| ----------------- | ------------------- |
| Deployment type   | Standalone          |
| CA name           | `HomelabCA`         |
| DNS name          | `ca.home.lab`       |
| Listening address | `:8443`             |
| First provisioner | `admin@ca.home.lab` |

Choose a strong password when prompted.

Once the wizard finishes, step-ca generates the root certificate, intermediate certificate, private keys, and configuration files.

The important files are stored inside `/home/step` in the container.

The root certificate is what clients will trust. The intermediate CA is used to issue certificates.

For a more secure setup, keep the root private key offline and use the intermediate CA for day-to-day certificate issuance. For this initial lab, I'm keeping the setup simple.

## 2. Configure the CA password

The CA needs access to the password used to protect its private keys.

Open a temporary shell inside the container:

```bash
podman run --rm -it \
  -v step-ca:/home/step \
  docker.io/smallstep/step-ca \
  sh
```

Create the password file using the same password you entered during initialisation:

```bash
$ echo -n "My-Little-Secret5" > secrets/password
```

Make sure the CA configuration expects this password file. Otherwise, the container might fail to start.

Keep the password and CA private keys out of Git repositories and protect any backups containing them.

## 3. Enable ACME

Next, I want step-ca to support ACME.

ACME is the protocol that allows compatible clients to request and renew certificates automatically. This is particularly useful for services such as Caddy and Proxmox VE.

Add an ACME provisioner:

```bash
podman run --rm \
  -v step-ca:/home/step \
  docker.io/smallstep/step-ca \
  step ca provisioner add acme --type ACME
```

The CA configuration is updated with the new provisioner as shown below.

```bash
✔ CA Configuration: /home/step/config/ca.json

Success! Your `step-ca` config has been updated. To pick up the new configuration SIGHUP (kill -1 <pid>) or restart the step-ca process.
```

For my setup, the ACME directory URL is:

```
https://ca.home.lab:8443/acme/acme/directory
```

After changing the configuration, restart step-ca so the running service loads the changes.

One thing to remember: enabling ACME doesn't automatically make every service work. The ACME client and CA still need a supported way to validate that the requested hostname belongs to the service.

## 4. Start the CA

Start step-ca in the background:

```bash
podman run -d \
  --name step-ca \
  --restart=always \
  -p 8443:8443 \
  -v step-ca:/home/step \
  docker.io/smallstep/step-ca
```

Check that the container is running:

```bash
podman ps
podman logs step-ca
```

For a long-running homelab service, I'd eventually move this into a systemd-managed Podman service or Quadlet. That makes startup and recovery easier to manage.

Also, restrict access to port 8443 to the networks that actually need to use the CA.

## 5. Install step-cli on a client

Now let's configure a Debian client.

Install the required packages:

```bash
apt-get update && apt-get install -y --no-install-recommends curl gpg ca-certificates
```

Download Smallstep's repository signing key:

```bash
curl -fsSL \
  https://packages.smallstep.com/keys/apt/repo-signing-key.gpg \
  -o /etc/apt/keyrings/smallstep.asc
```

Add the repository:

```bash
cat <<'EOF' > /etc/apt/sources.list.d/smallstep.sources
Types: deb
URIs: https://packages.smallstep.com/stable/debian
Suites: debs
Components: main
Signed-By: /etc/apt/keyrings/smallstep.asc
EOF
```

Install step-cli:

```bash
apt-get update && apt-get install -y step-cli
```

That's the client side ready.

## 6. Trust the private CA

The next step is to tell the client to trust my CA.

During initialisation, step-ca displayed a root certificate fingerprint. I'll use that fingerprint to verify the CA during bootstrap.

```bash
step ca bootstrap \
  --ca-url https://ca.home.lab:8443 \
  --fingerprint YOUR_ROOT_CA_FINGERPRINT \
  --install
```

Replace `YOUR_ROOT_CA_FINGERPRINT` with the fingerprint from your own CA.

The command downloads the root certificate and configures step-cli. The `--install` option also attempts to install the root certificate into the system trust store.

This is what allows the client to trust certificates issued by my private CA.

### Check that the CA is working

Run:

```bash
curl https://ca.home.lab:8443/health
```

A healthy CA should return:

```bash
{"status":"ok"}
```

If it doesn't work, check DNS resolution, network connectivity, the container logs, and the client's certificate trust.

At this point, the CA is running and the client trusts it.

## 7. Connect Proxmox VE to step-ca

Now for the interesting part: using the private CA with Proxmox VE.

Proxmox supports ACME, so it can request certificates from a compatible ACME server instead of relying on manually managed certificates.

First, register an ACME account:

```bash
pvenode acme account register default \
  pvetest1@home.lab \
  --directory https://ca.home.lab:8443/acme/acme/directory
```

This registers the account, but it doesn't issue a certificate yet. You'll still need to configure the certificate hostname and an appropriate ACME challenge plugin.

### A quick note about ports 443, 8006, and 8443

While experimenting with Proxmox, I also looked at redirecting HTTPS traffic from port 443 to port 8006.

These ports have different jobs:

* **8443:** My step-ca API and ACME directory.
* **8006:** The Proxmox web interface.
* **80:** Used by ACME HTTP-01 validation.
* **443:** HTTPS traffic, including TLS-ALPN-01 validation when supported.

I initially tried this firewall rule:

```
iptables -t nat -I PREROUTING \
  --src 10.100.200.10 \
  --dst 10.100.200.20 \
  -p tcp --dport 443 \
  -j REDIRECT --to-ports 8006
```

The rule redirects matching traffic from port 443 to the Proxmox web interface on port 8006.

However, **this rule does not solve ACME HTTP-01 validation**.

HTTP-01 requires the ACME server to retrieve a temporary challenge response over HTTP on port 80. Redirecting HTTPS traffic to the Proxmox web interface doesn't provide that response.

If you're using HTTP-01, the challenge request must reach the ACME client's challenge server. Alternatively, DNS-01 validation uses a DNS TXT record and avoids the need for an HTTP challenge server.

For my homelab, the important thing is to choose a validation method that works with both step-ca and the Proxmox ACME client, rather than assuming a port redirect will solve everything.

### Should you keep the redirect?

If you have another specific reason to use the redirect, you can make it persistent through `/etc/network/interfaces`:

```bash
post-up iptables -t nat -I PREROUTING --src 10.100.200.10 --dst 10.100.200.20 -p tcp --dport 443 -j REDIRECT --to-ports 8006
post-down iptables -t nat -D PREROUTING --src 10.100.200.10 --dst 10.100.200.20 -p tcp --dport 443 -j REDIRECT --to-ports 8006
```

Add these lines to the appropriate interface stanza as shown below, and test carefully if you're managing the node remotely.

```bash
vi /etc/network/interfaces
auto lo
iface lo inet loopback

iface ens18 inet manual

auto vmbr0
iface vmbr0 inet static
	address 10.100.200.20/24
	gateway 10.100.200.1
	bridge-ports ens18
	bridge-stp off
	bridge-fd 0
	post-up iptables -t nat -I PREROUTING --src 10.100.200.10 --dst 10.100.200.20 -p tcp --dport 443 -j REDIRECT --to-ports 8006
	post-down iptables -t nat -D PREROUTING --src 10.100.200.10 --dst 10.100.200.20 -p tcp --dport 443 -j REDIRECT --to-ports 8006
```

For certificate issuance alone, don't add this rule unless you have a separate networking requirement for it.

## 8. Install the root CA certificate in Firefox

After setting up step-ca, I noticed one more thing: trusting the CA at the operating system level doesn't always mean Firefox will trust it.

Firefox can use its own certificate store, so let's import our private root certificate directly into the browser.

### Step 1: Locate the root certificate

After running `step ca bootstrap`, the root certificate should be available at:

```
~/.step/certs/root_ca.crt
```

If you're importing it on another computer, securely copy this public certificate to that machine first.

### Step 2: Open Firefox Certificate Manager

Open Firefox and follow these steps:

1. Open **Settings**.
2. Select **Privacy & Security**.
3. Scroll down to the **Certificates** section.
4. Click **View Certificates**.
5. Select the **Authorities** tab.
6. Click **Import**.

### Step 3: Import the root certificate

Select the `root_ca.crt` file.

Firefox will ask which purposes you want to trust the CA for. Select:

**Trust this CA to identify websites.**

Click **OK** to finish importing the certificate.

You don't need to import the intermediate certificate separately as a trust anchor. Your services should present the appropriate intermediate certificate chain when serving their certificates.

### Step 4: Test the configuration

Open your CA health endpoint in Firefox:

```
https://ca.home.lab:8443/health
```

If the certificate chain is correct, the hostname matches the certificate, and the CA is reachable, Firefox should display the health response without a certificate warning.

You can also test another internal service after issuing it a certificate from step-ca.

If Firefox still shows a warning, check the certificate's hostname, validity period, and issuing chain, and confirm that you imported the correct root certificate.

That's it! Firefox can now trust certificates issued by your private CA.

**A quick security reminder:** Only import a root certificate after verifying its fingerprint through a trusted channel. A trusted root can authorise certificates for websites, so don't import unknown CA certificates.

## 9. A few things worth remembering

Before putting the CA into regular use, there are a few things I'd take care of:

* **Backups:** Keep secure backups of the CA database, configuration, and private keys.
* **Root CA security:** Ideally, keep the root private key offline and use the intermediate CA for issuing certificates.
* **Network access:** Don't expose the CA unnecessarily.
* **Certificate renewal:** Test ACME renewal before certificates expire.
* **Secrets:** Never commit passwords or private keys to Git.
* **Automation:** Once the setup works, consider managing the deployment with Podman Quadlet and Ansible.

## Conclusion

Setting up step-ca with Podman gives me a simple foundation for certificate management in my homelab.

Instead of dealing with individual self-signed certificates, I can use one private CA to establish trust across my internal services. ACME takes this a step further by automating certificate issuance and renewal for compatible applications.

The next step is to integrate the CA properly with Proxmox VE and my reverse proxy, then automate more of the process.

One step at a time - that's how I like to build my homelab.
