Try It Out

To test Atlantis, we will set up a test repository in GitHub with sample Terraform code and use an Ngrok service to connect Atlantis to the GitHub webhook so it can detect PRs.

Install Ngrok on your host. Follow the official instructions from Ngrok.

Authenticate your client with an auth token before the next step:

ngrok config add-authtoken {ngrok_token}

The token is available in your Ngrok account at https://dashboard.ngrok.com/get-started/your-authtoken.

Expose your local Ngrok service over port 4141 to the public internet via a secure HTTPS tunnel:

ngrok http 4141

You should see a confirmation such as:

ngrok                                                                                           (Ctrl+C to quit)
                                                                                                                
🧠 Call internal services from your gateway: https://ngrok.com/r/http-request

🤫 Decouple policy and sensitive data with vaults: https://ngrok.com/r/secrets                            
                                                                                                                
Session Status                online                                                                            
Account                       *username* (Plan: Free)                                                                 
Version                       3.24.0                                                                            
Region                        United States (us)                                                                
Web Interface                 http://127.0.0.1:4040                                                             
Forwarding                    https://0ec8262222f9.ngrok-free.app -> http://localhost:4141                      
                                                                                                                
Connections                   ttl     opn     rt1     rt5     p50     p90                                       
                              0       0       0.00    0.00    0.00    0.00  

The forwarding address is a public URL with a unique ID that proxies requests to your local machine's address at localhost:4141.

Write down the forwarding address. We will use it to set up the GitHub webhook. In our example, it is https://0ec8262222f9.ngrok-free.app.

Create a GitHub repository to use for the test. Next, download the test file main.tf provided here and commit it to the repository to simulate your Terraform code.

Download the file main.tf (link to preview the file):

wget -O main.tf https://raw.githubusercontent.com/minimusio/examples/main/atlantis/main.tf

In the same Github repository, navigate to > Settings > Webhooks and click Add Webhook.

Fill in the form fields:

• Payload URL: Paste the Ngrok forwarding address from the previous step and append /events to it. For example, https://0ec8262222f9.ngrok-free.app/events.

• Content type: application/json

• Secret: Create a password and make sure to write it down as we will need it to set up the Atlantis container. The secret can be any random string.

• SSL verification: disabled (Just for this test. It's not recommended in general.)

• Which events would you like to trigger this webhook?: Send me everything. (If you prefer, you can select a different option for this test.)

• Active: This should be enabled by default. It activates the webhook and keeps it updated.

Save the webhook.

Before you can run the Atlantis image, you need to prepare a GitHub token. To create a new token, go to your personal GitHub account settings at > Developer Settings > Personal access tokens > Tokens (classic). Give the token the following permissions:

• repo
• admin:repo_hook

Run the Atlantis container (after updating all the placeholders):

docker run --rm --name minimus-atlantis \
    -e ATLANTIS_REPO_ALLOWLIST="github.com/{YOUR_GITHUB_USERNAME}/{YOUR_REPO}" \
    -e ATLANTIS_GH_USER="{YOUR_GITHUB_USERNAME}" \
    -e ATLANTIS_GH_TOKEN="{YOUR_GITHUB_TOKEN}" \
    -e ATLANTIS_GH_WEBHOOK_SECRET="{YOUR_GITHUB_WEBHOOK_SECRET}" \
    -e ATLANTIS_ATLANTIS_URL="{FORWARDING_URL}" \
    -p 4141:4141 \
    reg.mini.dev/atlantis server

Check the logs to make sure the container is up and running:

docker logs minimus-atlantis 2>&1 | grep "Atlantis started"

In your GitHub repository, make a change to the code in the sample file main.tf and create a pull request. Make sure that you choose the option to create a new branch and don't commit directly to the main branch.

You should see your pull request updated in the Atlantis web UI at http://localhost:4141. The PR will also be registered in the Ngrok interface at http://127.0.0.1:4040.

Your Atlantis setup is now complete.

Technical Considerations

The Atlantis image provided by Minimus is a slim, security-hardened alternative to the public image. The images are largely interchangeable, with a few differences as noted below.

Terms & Info

This catalog is published by Minimus. All product names, logos, and marks, other than those belonging to Minimus, shown are owned by their respective rights holders and appear here only to identify the open source software each image contains. Minimus claims no ownership of those marks and implies no affiliation with, endorsement by, certification by, or sponsorship by any rights holder.

Images are provided "as-is" without warranty of any kind. "Hardened" refers to the security configuration applied at the time of build and does not constitute a guarantee of ongoing security or absence of vulnerabilities. The free tier is provided without support, SLA, or guaranteed patching timelines. Security updates may be applied to paid subscriptions before or instead of free tier images. By pulling or using any image you agree to our Terms of Use.