DPTCloud
Back to articles
Technology Insight

Automating Terraform Workflows on a VPS: A Complete Guide to Deploying and Configuring Atlantis for Pull Request Automation

May 30, 2026

Introduction to Infrastructure as Code and the Need for GitOps

In the modern DevOps landscape, Infrastructure as Code (IaC) has transitioned from a best practice to an absolute necessity. Tools like HashiCorp Terraform allow engineering teams to define, provision, and manage cloud infrastructure using declarative configuration files. However, as teams scale, managing Terraform state files and executing plans locally introduces significant challenges. Simultaneous runs can lead to state locks, configuration drift occurs when local changes are applied directly, and tracking who changed what becomes a logistical nightmare.

To solve these friction points, organizations are rapidly adopting GitOps for infrastructure management. GitOps centers the entire operations workflow around a version control system (VCS) like GitHub or GitLab. By treating Git repositories as the single source of truth for infrastructure, teams can leverage peer reviews, audit trails, and automated pipelines. This is where Atlantis enters the picture. Atlantis is an open-source application that listens for webhooks from your Git provider and executes Terraform commands directly within your Pull Requests (PRs). In this guide, we will walk through configuring a self-hosted Atlantis instance on a Virtual Private Server (VPS) to achieve fully automated, highly secure Terraform reviews and approvals.

Why Choose Atlantis on a VPS for Your Terraform Workflows?

While managed CI/CD platforms like GitHub Actions or GitLab CI can run Terraform scripts, they often require complex management of runner environments, secrets, and concurrent execution states. Atlantis offers several unique advantages specifically tailored for Terraform orchestration:

  • Real-time Feedback in Pull Requests: Team members see the exact output of terraform plan directly in the PR comments, eliminating the need to log into external CI systems to check build logs.
  • State Locking via Git: Atlantis automatically locks the specific directory or workspace being modified in a PR. This prevents other developers from running concurrent updates on the same infrastructure, completely avoiding state corruption.
  • Enhanced Security and Isolation: Hosting Atlantis on your own VPS ensures that sensitive infrastructure credentials, cloud API tokens, and internal architecture maps never leave your private network boundary.
  • Cost Efficiency: Unlike managed IaC platforms that charge per user or per run minute, a VPS provides a predictable, low-cost environment with complete resource control.

By hosting Atlantis on a dedicated VPS, you bridge the gap between developer collaboration and infrastructure security, enabling a seamless "Plan in PR, Apply on Merge" workflow.

Prerequisites and Environment Setup

Before launching into the installation phase, ensure that your environment meets the following baseline requirements:

  1. A Provisioned VPS: A virtual private server running a modern Linux distribution (e.g., Ubuntu 22.04 LTS or newer) with at least 2 vCPUs and 4GB of RAM.
  2. Domain Name and SSL Certificate: A domain or subdomain (e.g., atlantis.yourcompany.com) pointing to your VPS IP address. Atlantis handles webhooks, meaning your Git provider must be able to reach it over secure HTTPS.
  3. Git Provider Credentials: An administrative account on GitHub, GitLab, or Bitbucket to create webhooks and generate a Personal Access Token (PAT).
  4. Cloud Provider Access: Relevant IAM roles or access keys (e.g., AWS, Azure, or GCP credentials) configured on the VPS so Terraform can interact with your cloud provider.
Security Warning: Never expose Atlantis over unencrypted HTTP (Port 80) to the public internet. Because Atlantis possesses administrative access to your cloud infrastructure, securing your communication channel with TLS/SSL is mandatory.

Step-by-Step Installation and Configuration

Step 1: Installing Atlantis and Terraform Binaries

First, access your VPS via SSH. We will download the official pre-compiled binaries for both Terraform and Atlantis. It is critical to ensure that the Terraform version installed on the VPS matches the version specified in your infrastructure code repositories.

# Update the system repository and install core dependencies
sudo apt-get update && sudo apt-get install -y unzip curl wget git

# Download and install Terraform
TERRAFORM_VERSION="1.7.0"
wget [https://releases.hashicorp.com/terraform/$](https://releases.hashicorp.com/terraform/$){TERRAFORM_VERSION}/terraform_${TERRAFORM_VERSION}_linux_amd64.zip
unzip terraform_${TERRAFORM_VERSION}_linux_amd64.zip
sudo mv terraform /usr/local/bin/

# Download and install Atlantis
ATLANTIS_VERSION="0.27.0"
wget [https://github.com/runatlantis/atlantis/releases/download/v$](https://github.com/runatlantis/atlantis/releases/download/v$){ATLANTIS_VERSION}/atlantis_linux_amd64.zip
unzip atlantis_linux_amd64.zip
sudo mv atlantis /usr/local/bin/

Verify both installations by running terraform -v and atlantis version to confirm that the binaries are correctly placed in your system path.

Step 2: Configuring Git Provider Authentication (GitHub Example)

Atlantis requires access to your repositories to post comments, read files, and manage pull request statuses. To configure this for GitHub:

  • Navigate to Developer Settings > Personal Access Tokens > Fine-grained tokens on GitHub.
  • Generate a new token with Read & Write access to Pull Requests, Repository Contents, and Webhooks.
  • Copy this token securely; it will act as your ATLANTIS_GH_TOKEN.
  • Generate a random, secure string to serve as a webhook secret (e.g., using openssl rand -hex 32). This will be your ATLANTIS_GH_WEBHOOK_SECRET.

Step 3: Creating the Server Configuration File

Instead of passing extensive command-line flags, create a centralized, structured configuration file for Atlantis. Create a file at /etc/atlantis/server.yaml:

atlantis-url: "[https://atlantis.yourcompany.com](https://atlantis.yourcompany.com)"
port: 4141
gh-user: "atlantis-bot"
gh-token: "your_github_personal_access_token"
gh-webhook-secret: "your_generated_webhook_secret"
repo-allowlist: "[github.com/your-organization/](https://github.com/your-organization/)*"
data-dir: "/var/lib/atlantis"
log-level: "info"

Step 4: Setting Up a Systemd Service

To guarantee that Atlantis runs reliably in the background and restarts automatically if the VPS reboots, configure it as a systemd system service. Create the file /etc/systemd/system/atlantis.service:

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

[Service]
Type=simple
User=atlantis
WorkingDirectory=/var/lib/atlantis
ExecStart=/usr/local/bin/atlantis server --config /etc/atlantis/server.yaml
Restart=always
RestartSec=5
Environment=AWS_ACCESS_KEY_ID=your_key AWS_SECRET_ACCESS_KEY=your_secret

[Install]
WantedBy=multi-user.target

Before starting the service, make sure to create the dedicated atlantis system user and set appropriate directory permissions:

sudo useradd --system --no-create-home atlantis
sudo mkdir -p /var/lib/atlantis /etc/atlantis
sudo chown -R atlantis:atlantis /var/lib/atlantis /etc/atlantis

# Start and enable the service
sudo systemctl daemon-reload
sudo systemctl start atlantis
sudo systemctl enable atlantis

Configuring the Webhook and Server Proxy

To safely route external traffic from your Git provider to your internal Atlantis application layer running on port 4141, you should set up a reverse proxy using Nginx and secure it with a free Let's Encrypt SSL certificate via Certbot.

# Install Nginx and Certbot
sudo apt-get install -y nginx certbot python3-certbot-nginx

Configure an Nginx server block to forward incoming requests securely. Edit /etc/nginx/sites-available/atlantis to forward upstream traffic to http://localhost:4141, then enable the site and apply the SSL configurations using Certbot:

sudo certbot --nginx -d atlantis.yourcompany.com

With Nginx operational and SSL actively encrypting traffic, head back to your GitHub repository or organization settings. Add a new Webhook with the Payload URL set to [https://atlantis.yourcompany.com/events](https://atlantis.yourcompany.com/events), choose application/json as the content type, input your webhook secret, and select individual events including Issue comments, Pull request reviews, and Pull requests.

The GitOps Lifecycle: Running a Pull Request

Now that your execution engine is live, your development lifecycle shifts entirely to the pull request interface. Let's explore how engineering teams interact with Atlantis during a typical code lifecycle:

  1. Creating the Feature Branch: A developer creates a new Git branch and modifies a Terraform file, such as adding a new AWS S3 bucket instance or altering an IAM policy rule.
  2. Opening the Pull Request: The developer pushes the branch to the remote repository and opens a Pull Request against the main branch.
  3. Automated Evaluation: The webhook fires instantly. Atlantis intercepts the event, clones the branch, runs an isolated terraform init, and executes terraform plan. The complete infrastructure plan output is automatically formatted and posted as a comment inside the PR description.
  4. Peer Review and Commenting: Senior engineers inspect the proposed changes displayed directly in the comment. If alterations are needed, developers push new commits, causing Atlantis to automatically regenerate the plan.
  5. Applying the Changes: Once the team approves the PR, a user triggers the deployment phase by writing a single comment: atlantis apply. Atlantis runs the execution phase on the VPS server and streams back the success logs.
  6. Finalizing State: With the infrastructure successfully modified, the PR automatically merges into the stable main branch, keeping code and actual state perfectly synchronized.

Production Best Practices and Security Hardening

Deploying tools with infrastructure execution access requires careful hardening. Implement these production-grade rules on your VPS:

  • Implement Strict Repository Allowlists: Never set your repo-allowlist configuration flag to *. Explicitly define your corporate GitHub organization or specific repo paths to avoid unauthorized code execution on your server.
  • Utilize Server-Side Repo Configuration (atlantis.yaml): Require an internal atlantis.yaml file within your code repositories. This gives you granular control over pre-workflow validation steps, such as enforcement of security scanning tools like tfsec or Checkov prior to running the plan phase.
  • Regular State Backups: Ensure that your underlying backend architecture utilizes native state locking mechanisms (e.g., Amazon DynamoDB tables combined with encrypted S3 buckets) to provide a secondary layer of state safety alongside Atlantis' internal locks.

Conclusion

By establishing an automated Atlantis deployment on a VPS, you successfully transform infrastructure configuration from a high-risk manual workflow into a structured, visible, and secure collaborative operations engine. Teams gain velocity through transparent peer reviews, while operations managers maintain strict control over credential exposure, cost metrics, and state preservation. Embrace this modern GitOps standard to bring true predictability and scalability to your cloud orchestration pipeline.

Automating Terraform Workflows on a VPS: A Complete Guide to Deploying and Configuring Atlantis for Pull Request Automation | DPTCloud