What Is This Guide About?

This guide will walk you through installing Lego — a free tool that helps you get SSL certificates for your websites automatically. SSL certificates are what make your website secure (they're the reason you see a padlock icon in your browser).

Lego works with a special service called an ACME server, which issues SSL certificates. Don't worry — you don't need to understand exactly how it works. Just follow the steps in this guide and you'll be set up in no time.

Before You Begin

Before you start installing anything, make sure you have the following ready. If you're missing any of these, reach out to your IT administrator.

• A computer running: Windows, macOS, Linux, or FreeBSD (64-bit)

• A Cloudflare account (or another DNS provider) with API credentials

• EAB credentials — Special login keys provided by your ACME server administrator. Think of them as a username and password for your certificate account.

• Administrator access (admin/sudo rights on your computer)

Why Use Lego?

There are several tools available to get SSL certificates. Here's a simple comparison to help you understand why Lego is a great choice:

In short, Lego requires no extra software, runs natively on all major operating systems including Windows, and supports a huge number of DNS providers.

Step-by-Step Installation

Choose the section that matches your operating system. Each section has simple copy-paste commands. If you're not comfortable running commands, ask your IT team to do this step for you.

Windows Installation

The easiest way to install Lego on Windows is to download the program file directly. Here's how:

$LegoVersion = "v4.15.0"
$DownloadUrl = "https://github.com/go-acme/lego/releases/download/$LegoVersion/lego_${LegoVersion}_windows_amd64.zip"

Invoke-WebRequest -Uri $DownloadUrl -OutFile "lego.zip"
Expand-Archive -Path "lego.zip" -DestinationPath "C:\Program Files\Lego" -Force
Remove-Item "lego.zip"

$env:Path += ";C:\Program Files\Lego"
[Environment]::SetEnvironmentVariable("Path", $env:Path, [EnvironmentVariableTarget]::Machine)

lego --version

If it worked, you'll see something like:

lego version 4.15.0 windows/amd64

Alternative Windows methods (if you use a package manager):

• Chocolatey: choco install lego

• Scoop: scoop install lego

Linux Installation

LEGO_VERSION="v4.15.0"

wget https://github.com/go-acme/lego/releases/download/${LEGO_VERSION}/lego_${LEGO_VERSION}_linux_amd64.tar.gz

tar -xzf lego_${LEGO_VERSION}_linux_amd64.tar.gz

sudo mv lego /usr/local/bin/
sudo chmod +x /usr/local/bin/lego

lego --version

• On Arch Linux: sudo pacman -S lego

• On any system with Homebrew: brew install lego

macOS Installation

brew install lego

If you don't have Homebrew, you can download the binary directly (similar to Linux instructions above, but use the darwin_amd64 version).

lego --version

Docker Installation (Optional)

If your team uses Docker containers, you can run Lego inside a container without installing it directly on your system:

docker pull goacme/lego:latest

# Test it works:
docker run -it --rm -v $HOME/.lego:/data goacme/lego:latest --version

Setting Up Your Configuration

Now that Lego is installed, you need to tell it where your certificate server is and how to connect to it. This is done using a configuration file with your credentials and settings.

Understanding the Folder Structure

Lego automatically creates a folder on your computer to store your certificates and account information. Here's what it looks like:

Creating the Configuration File

You need to create a file that stores all your settings — think of it like a settings profile for Lego.

On Linux or macOS

mkdir -p ~/.lego/config

nano ~/.lego/config/acme-server.env

# ACME Server address (provided by your IT admin)
export ACME_SERVER="https://acme.example.com/acme/directory"

# Your EAB login credentials (provided by your IT admin)
export EAB_KEY_ID="XXXXXXXXXXXXXXXXXXXXXXXX"
export EAB_HMAC_KEY="XXXXXXXXXXXXXXXXXXXXXXXX"

# Your email address
export EMAIL="you@yourcompany.com"

# Cloudflare API Token (from your Cloudflare account)
export CLOUDFLARE_DNS_API_TOKEN="XXXXXXXXXXXXXXXXXXXXXXXX"
export CLOUDFLARE_ZONE_API_TOKEN="XXXXXXXXXXXXXXXXXXXXXXXX"

# DNS settings (these defaults usually work fine)
export CLOUDFLARE_PROPAGATION_TIMEOUT="600"
export CLOUDFLARE_POLLING_INTERVAL="10"
export CLOUDFLARE_TTL="120"

chmod 600 ~/.lego/config/acme-server.env

source ~/.lego/config/acme-server.env

On Windows

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.lego\config"

@"
# ACME Server address
`$env:ACME_SERVER = "https://acme.example.com/acme/directory"
`$env:EAB_KEY_ID = "XXXXXXXXXXXXXXXXXXXXXXXX"
`$env:EAB_HMAC_KEY = "XXXXXXXXXXXXXXXXXXXXXXXX"
`$env:EMAIL = "you@yourcompany.com"
`$env:CLOUDFLARE_DNS_API_TOKEN = "XXXXXXXXXXXXXXXXXXXXXXXX"
`$env:CLOUDFLARE_ZONE_API_TOKEN = "XXXXXXXXXXXXXXXXXXXXXXXX"
`$env:CLOUDFLARE_PROPAGATION_TIMEOUT = "600"
"@ | Out-File -FilePath "$env:USERPROFILE\.lego\config\acme-server.ps1" -Encoding UTF8

. "$env:USERPROFILE\.lego\config\acme-server.ps1"

Setting Up Your Cloudflare API Token

Lego needs permission to temporarily add a record to your DNS (Domain Name System) to prove you own the domain. This is done automatically using a Cloudflare API token.

How to Create a Cloudflare API Token

1. Log in to your Cloudflare account at cloudflare.com

2. Click on your profile icon (top right) ? select My Profile

3. Click on API Tokens in the left menu

4. Click Create Token

5. Choose the template: "Edit zone DNS"

6. Set the following permissions:

• Zone ? DNS ? Edit

• Zone ? Zone ? Read

7. Under "Zone Resources", select your specific domain (e.g. example.com)

8. Click "Continue to summary" ? then "Create Token"

9. Copy the token and paste it into your configuration file

Test That Your Cloudflare Token Works

After adding your token to the config file, run this command to make sure it's valid:

Linux / macOS

curl -X GET "https://api.cloudflare.com/client/v4/user/tokens/verify" \
  -H "Authorization: Bearer $CLOUDFLARE_DNS_API_TOKEN" \
  -H "Content-Type: application/json"

Windows

Invoke-RestMethod -Uri "https://api.cloudflare.com/client/v4/user/tokens/verify" `
  -Headers @{ "Authorization" = "Bearer $env:CLOUDFLARE_DNS_API_TOKEN" }

If your token is valid, you'll see a response that includes:

{ "success": true, "result": { "status": "active" } }

Using a Different DNS Provider?

Lego supports over 100 DNS providers. If you use something other than Cloudflare, here are the settings for some common ones:

Verifying Everything Is Working

Before you request your first certificate, let's make sure everything is set up correctly. Run through these three checks:

Check 1 — Lego Is Installed Correctly

lego --version

Expected result: lego version 4.15.0 linux/amd64 (or your OS)

Check 2 — Your Settings Are Loaded

Linux / macOS

echo "ACME Server: $ACME_SERVER"
echo "Email: $EMAIL"

Windows

Write-Host "ACME Server: $env:ACME_SERVER"
Write-Host "Email: $env:EMAIL"

You should see the values you entered, not blank lines.

Check 3 — You Can Reach the Certificate Server

Linux / macOS

curl -I "$ACME_SERVER"

Windows

Invoke-WebRequest -Uri $env:ACME_SERVER -Method Head

If it's working, you'll get a response (not an error). The response will contain information like newAccount and newOrder — this means the server is reachable.

Account Registration — Automatic!

Unlike some other tools, Lego does NOT require you to manually register an account. It does this automatically the first time you request a certificate.

Once you request your first certificate, Lego will create an account using your EAB credentials and save your account details in the ~/.lego/accounts/ folder.

Pre-Flight Checklist

Before moving on to requesting your first certificate, confirm you've completed all the steps below:

Troubleshooting Common Problems

Problem: 'lego: command not found'

This means your system can't find Lego. The most common cause is that the folder where Lego is installed isn't in your system's PATH.

Fix for Linux / macOS

# Check your current PATH
echo $PATH

# If /usr/local/bin is not listed, add it:
export PATH="/usr/local/bin:$PATH"

Fix for Windows

# Add Lego to PATH permanently:
[Environment]::SetEnvironmentVariable("Path",
  "$env:Path;C:\Program Files\Lego",
  [EnvironmentVariableTarget]::Machine)

Problem: 'Permission Denied'

This means Lego doesn't have permission to run. Fix it with:

sudo chmod +x /usr/local/bin/lego

Problem: 'Invalid API Token' from Cloudflare

This means your Cloudflare token is wrong or expired. To fix this:

1. Log into your Cloudflare account

2. Go to My Profile ? API Tokens

3. Check that the token has Zone / DNS / Edit permission

4. If it's expired or wrong, create a new token and update your config file

Problem: Cannot Connect to the Certificate Server

If you see an error like 'Unable to connect to the remote server':

1. Double-check that your ACME_SERVER address is typed correctly in your config file

2. Make sure your firewall allows outbound connections on port 443 (HTTPS)

3. Try opening the server address in a web browser to see if it loads

4. Contact your IT administrator if the above steps don't help

Problem: 'EAB Credentials Invalid'

If you see an error about externalAccountRequired:

1. Check that EAB_KEY_ID is copied correctly from the email/document your admin provided

2. Check that EAB_HMAC_KEY is also copied correctly (no extra spaces)

3. If you're still stuck, contact your ACME server administrator for new credentials

What Comes Next?

Congratulations! You have successfully installed and configured Lego. Here is what you can do next:

Link to: LEGO DEPLOYMENT GUIDE

Resources and Support

Quick Summary

Here is a recap of everything covered in this guide:

1. Installed Lego — a free, single-file tool for getting SSL certificates

2. Configured your settings — set up your ACME server address, email, and EAB credentials

3. Connected your DNS provider — set up your Cloudflare (or other) API token

4. Verified everything works — confirmed Lego is installed, settings are loaded, and the server is reachable

You are now ready to request your first SSL certificate!