<a id="tutorial-getting-started"></a>

# Deploy the HAProxy charm

In this tutorial we’ll deploy the HAProxy charm to provide ingress to a backend application. This tutorial is done on LXD and assumes that you have a Juju controller bootstrapped and a machine model to deploy charms.

<a id="tutorial-requirements"></a>

## Requirements

You will need a working station, e.g., a laptop, with AMD64 architecture. Your working station
should have at least 4 CPU cores, 8 GB of RAM, and 50 GB of disk space.

<!-- SPREAD SKIP -->

#### TIP
You can use Multipass to create an isolated environment by running:

```default
multipass launch 26.04 --name charm-tutorial-vm --cpus 4 --memory 8G --disk 50G
```

<!-- SPREAD SKIP END -->

This tutorial requires the following software to be installed on your working station
(either locally or in the Multipass VM):

- Juju 3.6
- LXD 5.21.4

Use [Concierge](https://github.com/canonical/concierge) to set up Juju and LXD:

```default
sudo snap install --classic concierge
sudo concierge prepare -p machine
```

This first command installs Concierge, and the second command uses Concierge to install
and configure Juju and LXD.

For this tutorial, Juju must be bootstrapped to a LXD controller. Concierge should
complete this step for you, and you can verify by checking for `msg="Bootstrapped Juju" provider=lxd`
in the terminal output and by running `juju controllers`.

If Concierge did not perform the bootstrap, run:

```bash
juju bootstrap lxd tutorial-controller
```

## Set up a tutorial model

To manage resources effectively and to separate this tutorial’s workload from your usual work, create a new model using the following command:

```default
juju add-model haproxy-tutorial
```

## Deploy the HAProxy charm

We will deploy charm from Charmhub using the `3.2/edge` channel:

```default
juju deploy haproxy --channel=3.2/edge
```

## Configure TLS

HAProxy enforces HTTPS when using the `haproxy-route` relation. To set up the TLS for the HAProxy charm, deploy the `self-signed-certificates` charm and integrate with the HAProxy charm:

```default
juju deploy self-signed-certificates
juju integrate haproxy:certificates self-signed-certificates
```

Once all the application has settled into an “Idle” state, we can verify by sending a request to the HAProxy’s IP address:

<!-- SPREAD
juju wait-for application haproxy --query='status=="active"' --timeout 10m
-->
```sh
HAPROXY_IP=$(juju status --format json | jq -r '.applications.haproxy.units."haproxy/0"."public-address"')
curl $HAPROXY_IP
```

If successful, the terminal will output:
If successful, the terminal will output:

```text
Default page for the haproxy-operator charm
```

## Deploy the backend application

For this tutorial we’ll use the [Pollen charm](https://charmhub.io/pollen). Start by deploying the Pollen charm:

```sh
juju deploy pollen --channel=latest/edge
```

Configure a hostname for HAProxy and integrate the Pollen charm with HAProxy:

```sh
juju config haproxy external-hostname=pollen.internal
juju integrate pollen haproxy:haproxy-route
```

Let’s check that the request has been properly proxied to the backend service using the `pollinate` script:

<!-- SPREAD
juju wait-for application haproxy --query='status=="active"' --timeout 10m
juju wait-for application pollen --query='status=="active"' --timeout 10m
# pollinate cannot log in the spread environment (logger: Operation not
# permitted), so verify the route with curl instead. Pollen answers plain curl
# requests with a 400 and a message pointing at the pollinate client.
HAPROXY_IP=$(juju status --format json | jq -r '.applications.haproxy.units."haproxy/0"."public-address"')
curl -k -sS --retry 30 --retry-delay 2 --retry-connrefused \\
  --resolve "pollen.internal:443:${HAPROXY_IP}" https://pollen.internal \\
  | grep -q "Please use the pollinate client"
-->
<!-- SPREAD SKIP -->
```sh
HAPROXY_IP=$(juju status --format json | jq -r '.applications.haproxy.units."haproxy/0"."public-address"')
echo "$HAPROXY_IP pollen.internal" | sudo tee /etc/hosts
sudo pollinate -s https://pollen.internal -r -i
```

<!-- SPREAD SKIP END -->

If successful, you should see a success message in the terminal:

```text
<13>Dec 17 20:45:02 pollinate[59078]: system was previously seeded at [2025-12-17 00:08:36.226000000 +0100]
<13>Dec 17 20:45:02 pollinate[59078]: client sent challenge to [https://pollen.internal]
<13>Dec 17 20:45:02 pollinate[59078]: client verified challenge/response with [https://pollen.internal]
<13>Dec 17 20:45:02 pollinate[59078]: client hashed response from [https://pollen.internal]
<13>Dec 17 20:45:02 pollinate[59078]: client successfully seeded [/dev/urandom]
```

## Clean up the environment

Well done! You’ve successfully completed the HAProxy tutorial.

To remove the model environment you created, use the following command:

<!-- SPREAD SKIP -->
```default
juju destroy-model haproxy-tutorial --no-prompt
```

<!-- SPREAD SKIP END -->
<!-- SPREAD
juju destroy-model haproxy-tutorial --no-prompt --force
-->

## Next steps

Check out these advanced guides to learn how to use HAProxy to provide load balancing for different protocols.

* [How to provide load balancing for an FTP server](https://canonical.com/juju/docs/haproxy-charm/latest/how-to/loadbalancing-for-an-ftp-server/index.html.md#how-to-loadbalancing-for-an-ftp-server)
* [How to provide load balancing for a gRPC server](https://canonical.com/juju/docs/haproxy-charm/latest/how-to/loadbalancing-for-a-grpc-server/index.html.md#how-to-loadbalancing-for-a-grpc-server)
