Automating Terraform Workflows: A Comprehensive Guide to Deploying Atlantis on a VPS for Pull Request GitOps

Introduction to GitOps and Terraform Automation

In modern cloud engineering, Infrastructure as Code (IaC) has transitioned from a best practice to an absolute necessity. Terraform by HashiCorp remains the industry standard for provisioning complex cloud topologies. However, as DevOps and platform engineering teams scale, managing Terraform states, ensuring compliance, and avoiding concurrent execution conflicts (state locking issues) become significant operational bottlenecks.

Traditionally, engineers run terraform plan and terraform apply locally from their workstations or trigger them via generic CI/CD pipelines (like GitHub Actions or GitLab CI). While functional, these approaches lack visibility and centralized collaboration. This is where Atlantis introduces a paradigm shift. Atlantis is an open-source application that listens for webhook events from your Git provider (GitHub, GitLab, Bitbucket) and executes Terraform commands directly within the context of a Pull Request (PR). By adopting Atlantis, you bring the absolute core principles of GitOps to your infrastructure management.

---

Why Deploy Atlantis on a Dedicated VPS?

While managed or containerized cloud native environments (like AWS EKS or Google GKE) are popular hosts for enterprise tools, deploying Atlantis on a dedicated Virtual Private Server (VPS) offers a balanced, cost-effective, and highly secure alternative for medium-sized enterprises and fast-growing startups.

• Predictable Costs: Unlike cloud-native cluster deployments that scale dynamically and incur hidden networking fees, a VPS offers a fixed monthly cost structure.
• State Locking and Isolation: Running Atlantis on a self-hosted VPS guarantees that your sensitive cloud credentials and Terraform state access logs remain within a perimeter completely under your control.
• Simplicity in Maintenance: Debugging configurations, updating Terraform binaries, and managing system dependencies on a Linux VPS is straightforward, avoiding the operational overhead of Kubernetes manifest management.

---

Prerequisites and Environment Architecture

Before initiating the installation process, ensure your infrastructure meets the following architectural and system requirements:

1. A Linux VPS: Ideally running Ubuntu 22.04 LTS or newer, with a minimum of 2 vCPUs, 4GB RAM, and 20GB of SSD storage.
2. Network Accessibility: A Public Static IP address assigned to your VPS, with ports 80 and 443 open to internet traffic, and port 4141 accessible internally.
3. Domain Name and SSL Certificate: A registered domain or subdomain (e.g., atlantis.yourcompany.com) pointed via an A Record to your VPS public IP.
4. Git Provider Credentials: Administrative access to a GitHub or GitLab repository to configure Webhooks and generate Personal Access Tokens (PAT).

Security Warning: Never run the Atlantis server application as the root user. Always create a dedicated, unprivileged system user specifically to handle the execution environment.

---

Step-by-Step Installation and Dependency Configuration

To begin setup, establish an SSH connection to your VPS and update the system repositories to patch existing vulnerabilities:

sudo apt update && sudo apt upgrade -y

1. Installing the Terraform Binary

Atlantis requires the exact versions of the Terraform CLI utilized by your development teams. Download and move the binary to your system path:

sudo apt-get update && sudo apt-get install -y gnupg software-properties-common curl
curl -fsSL [https://apt.releases.hashicorp.com/gpg](https://apt.releases.hashicorp.com/gpg) | sudo gpg --dearmor -o /usr/share/keyrings/hashicorp-archive-keyring.gpg
echo "deb [signed-by=/usr/share/keyrings/hashicorp-archive-keyring.gpg] [https://apt.releases.hashicorp.com/everyday-export](https://apt.releases.hashicorp.com/everyday-export) stable main" | sudo tee /etc/apt/sources.list.d/hashicorp.list
sudo apt update && sudo apt install terraform

2. Downloading and Installing Atlantis

Fetch the latest compiled release architecture of Atlantis from the official GitHub distribution page, extract it, and relocate it into the global executable path:

wget [https://github.com/runatlantis/atlantis/releases/download/v0.33.0/atlantis_linux_amd64.zip](https://github.com/runatlantis/atlantis/releases/download/v0.33.0/atlantis_linux_amd64.zip)
sudo apt install unzip
unzip atlantis_linux_amd64.zip
sudo mv atlantis /usr/local/bin/atlantis
atlantis --version

---

Integrating Atlantis with Your Git Provider (GitHub Example)

For Atlantis to orchestrate plans and applications via Git transactions, a bidirectional communication line must be forged between your VPS and GitHub.

1. Generating a Personal Access Token (PAT)

Navigate to your Git organization settings and generate a classic Developer Token with the following explicitly delegated scopes:

• repo (Full control of private repositories)
• admin:repo_hook (Full control of repository hooks)

Save this token securely; it functions as the password Atlantis uses to write comments back to your Pull Requests.

2. Configuring Webhook Secrets

Generate a unique, long cryptographic string that will be shared between GitHub and your Atlantis server instance to sign webhook payloads securely:

openssl rand -hex 32

---

Configuring Reverse Proxy and SSL via Nginx

Exposing Atlantis directly on port 4141 over unencrypted HTTP is an insecure vector. We will position Nginx as a reverse proxy coupled with Let's Encrypt to ensure all structural inputs are fully TLS-encrypted.

1. Nginx Virtual Host Configuration

Install Nginx and construct a dedicated configuration file:

sudo apt install nginx -y
sudo nano /etc/nginx/sites-available/atlantis

Insert the following server configuration block:server { listen 80; server_name atlantis.yourcompany.com; location / { proxy_pass [http://127.0.0.1:4141](http://127.0.0.1:4141); proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }

Enable the site configuration and restart Nginx:

sudo ln -s /etc/nginx/sites-available/atlantis /etc/nginx/sites-enabled/
sudo systemctl restart nginx

2. Acquiring TLS Certificates via Certbot

Execute Certbot to automate the acquisition and auto-renewal of your Let's Encrypt SSL certificates:

sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d atlantis.yourcompany.com

---

Deploying Atlantis as a Systemd Daemon

To ensure Atlantis boots reliably following unexpected server power cycles, you must establish it as a formal Linux background daemon system service.

Create a dedicated configuration parameters file at /etc/atlantis.env and restrict its read access to preserve secret parameters:

ATLANTIS_GH_USER="your-github-username"
ATLANTIS_GH_TOKEN="your-github-pat-token"
ATLANTIS_GH_WEBHOOK_SECRET="your-webhook-secret"
ATLANTIS_URL="[https://atlantis.yourcompany.com](https://atlantis.yourcompany.com)"
ATLANTIS_REPO_ALLOWLIST="[github.com/your-organization/](https://github.com/your-organization/)*"

Next, define the environment infrastructure system supervisor unit at /etc/systemd/system/atlantis.service:

[Unit]
Description=Atlantis Terraform Automation Daemon
After=network.target

[Service]
Type=simple
EnvironmentFile=/etc/atlantis.env
ExecStart=/usr/local/bin/atlantis server
Restart=always
RestartSec=5
User=atlantis
Group=atlantis

[Install]
WantedBy=multi-user.target

Reload the system initialization controller, enable the service, and verify runtime operational health:

sudo systemctl daemon-reload
sudo systemctl enable --now atlantis
sudo systemctl status atlantis

---

The GitOps Workflow in Action: Standard Operating Procedure

With Atlantis fully initialized on your VPS and hooks active within your repository, infrastructure engineering transitions to a completely transparent, auditable peer-reviewed ecosystem.

Phase 1: Proposing Changes

An engineer creates a feature isolation branch, makes structural updates to the underlying Terraform templates (such as adjusting auto-scaling thresholds or provisioning virtual storage buckets), and pushes the modifications upstream, initializing a new Pull Request.

Phase 2: Automated Planning

Upon detecting the PR creation, Atlantis intercepts the event, initiates an explicit backend state evaluation lock, and executes:

atlantis plan

The resulting infrastructure execution blueprint—highlighting structural additions, deletions, and non-destructive mutations—is printed automatically as a comprehensive markdown comment inside the pull request discussion timeline. Peers can review the exact architectural impact without leaving the code browser.

Phase 3: Formal Team Approval

Once senior stakeholders check the validity of the structural output changes, they issue a standard repository approval. Atlantis can be configured strictly to block modifications unless repository branch protection criteria are entirely satisfied.

Phase 4: Direct Application Execution

To apply changes to the production infrastructure, an authorized reviewer replies directly onto the pull request thread with the instruction:

atlantis apply

Atlantis executes the migration script from the VPS isolated container runtime environment, securely unlocks the remote state backend architecture, and commits the code change immediately to the main trunk branch. The feedback loop concludes cleanly without local credential leaks.

---

Conclusion and Operational Best Practices

Configuring Atlantis on a VPS delivers an enterprise-grade GitOps control loop framework that democratizes visibility over cloud provisioning while tightening structural guardrails. To keep this platform operating robustly, remember to schedule cron-driven backups of local Atlantis runtime parameters, enable audit logging, and routinely review access rules. By moving your execution layer away from arbitrary developer terminals and placing it squarely inside code reviews, your operations infrastructure scales confidently, maintaining consistency across every deployment cycle.