Skip to content

Repository files navigation

SquadHost 🎮☁️

💡 About the Project

SquadHost is an open-source, self-deployed on AWS, Aternos clone. I built this project to solve a specific problem: wanting complete control over a Minecraft server (soon modded) without paying 24/7 cloud hosting fees or waiting in free-tier queues.

Beyond solving a hosting problem, this project served as a practical proving ground for my engineering skills. I utilized it to actively learn Next.js and modern frontend development from scratch, while simultaneously designing a robust Python/Django backend and a highly automated DevOps pipeline.

🛠️ The Tech Stack

  • Frontend: Next.js, React, TypeScript, CSS (Built to learn Next.js and implement server-side proxying).
  • Backend: Python, Django, PostgreSQL, Django REST Framework.
  • DevOps & IaC: Terraform, Ansible, Docker.
  • Cloud Infrastructure: Amazon Web Services (EC2, S3, RDS, Lambda, IAM, VPC).
✅ Prerequisites

Before you begin, make sure you have the following:

  • Docker installed and running on your machine (installation instructions are in Step 4 for your OS).
  • An AWS Account with a valid credit card for identity verification (see Step 2).
  • ~10-15 minutes for the initial deployment to complete.

You do not need to install Terraform, Ansible, or the AWS CLI natively — everything runs inside Docker.

🚀 Installation & Deployment Guide

SquadHost is fully containerized. You do not need to install Terraform, Ansible, or the AWS CLI natively on your machine. You only need Docker and an Amazon Web Services (AWS) Account.

Step 1: Configure the .env File

First, we need to set up the configuration file where your AWS keys will eventually go.

  1. Clone this repository to your local machine.
  2. Locate the aws_credentials.env.template file in the root directory.
  3. Duplicate the file and rename the copy exactly to aws_credentials.env.
  4. Keep this file open. We will paste your Access Key, Secret Key, and Region into it in Step 3. (Note: This file is securely git-ignored to protect your AWS account).
  5. Important: Also change the default TF_VAR_db_username and TF_VAR_db_password values in this file to secure credentials of your choice before deploying.

Step 2: Create an AWS Account

⚠️ Important Billing Warning: AWS requires a valid credit card for identity verification. New accounts typically receive AWS Free Tier benefits, which act like a credit limit (often covering the first 750 hours of small EC2 instances per month for the first year).

However, AWS is not entirely free. Once your Free Tier limits are exhausted, or your trial period ends, AWS will charge your linked card. While SquadHost's kamikaze architecture is aggressively cost-optimized, you are still financially responsible for any cloud resources you consume.

The expected cost per month can reach up to $0.06 per hour of gameplay, which will be covered by the $100 credit provided to you by AWS.

  • If you do not already have an AWS account, please follow the Official AWS Account Creation Guide.
  • Crucial Step: Ensure you select the Basic support - Free plan during the final signup step.

Step 3: Generate AWS Credentials

To allow SquadHost to automatically provision your cloud infrastructure via Terraform, you need an AWS IAM Access Key.

  • Follow the Official AWS IAM Access Key Guide to generate your credentials.
  • Note: Ensure you create the keys for a user with programmatic access, and do not close the AWS window until you have copied the secret key!

Once generated, AWS will provide you with three critical pieces of information. Paste these directly into the aws_credentials.env file you created in Step 1:

  • AWS_ACCESS_KEY_ID: Your public account identifier.
  • AWS_SECRET_ACCESS_KEY: Your private password (AWS only shows this once!).
  • AWS_DEFAULT_REGION: The data center closest to you (e.g., ap-south-1, us-east-1). You can find this in the top right corner of your AWS console.

Step 4: OS-Specific Deployment

Select your operating system below to install Docker and ignite the cloud infrastructure.

🐧 Linux Deployment
  1. Install Docker (Universal Method): Run the official convenience script to automatically install Docker Engine for your specific Linux distribution:
  2. Add your user to the Docker group: This allows you to run Docker without sudo on every command:
  3. Apply the group change: This activates the new group without requiring a full logout:
  4. Script Permissions: Ensure the deployment scripts are executable:
  5. Ignite the Cloud: Run the spin_up script:
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
newgrp docker
chmod +x docker_spin_up.sh docker_kill_all.sh
./docker_spin_up.sh
  1. Nuclear Teardown: When you are done with Minecraft you can run this to delete everything in AWS to stop any billing.

⚠️ Warning: This will permanently delete any saved multiplayer worlds that have not been manually backed up from S3.

./docker_kill_all.sh
🪟 Windows Deployment
  1. Enable WSL 2: Docker Desktop requires WSL 2 to run on Windows. Search powershell in windows search and run as administrator then run this command:
wsl --install

⚠️ Note: If WSL was not already installed, you will need to restart your computer before continuing.

  1. Install Docker: Search for Docker Desktop in the Microsoft Store and install it. Once installed, open it from the Start Menu and wait for it to fully start — look for the Docker whale icon 🐳 in the system tray to stop animating.

Note: You might need to make a docker account. You can use your gmail for this.

  1. Verify Docker is running: Open PowerShell and run:
docker ps

If it returns a list (even empty), Docker is ready. If it returns an error, wait another 30 seconds and try again.

  1. Ignite the Cloud: Right-click docker_spin_up.bat and select Run as administrator:
docker_spin_up.bat

⚠️ Note: The window must stay open for the entire 10-15 minute deployment. Do NOT close it or press Ctrl+C.

  1. Nuclear Teardown: When you are done with Minecraft you can run this to delete everything in AWS to stop any billing.

⚠️ Warning: This will permanently delete any saved multiplayer worlds that have not been manually backed up from S3.

docker_kill_all.bat
🧠 Architecture Logic & Cloud Flow

SquadHost is not just a standard web application; it is a fully automated cloud orchestrator designed to solve the primary problem of cloud gaming: paying for idle servers.

To achieve a true "scale-to-zero" environment, this project utilizes a custom cloud lifecycle pipeline.

1. The Kamikaze Approach (Cost Optimization)

The core feature of SquadHost is the "Kamikaze" auto-deletion protocol. Cloud providers bill by the second for running EC2 instances. To minimize this, the architecture is designed to self-destruct when no longer needed.

  • The Watchdog: When a server is provisioned, a Python watchdog script (kamikaze_watchdog.py) is injected into the worker node via Ansible. This checks for number of Minecraft servers running and if there are exactly 0 servers for 10 minutes. This script starts the Self-Termination.
  • Inactivity Monitoring: This script continuously polls the Dockerized Minecraft container via RCON to check the active player count.
  • The Server Termination: If the player count remains at exactly 0 for 8 minutes, the script triggers the shutdown sequence and follows the file save procedure.
  • Self-Termination: The script safely stops the container, zips the world files, pushes the backup to AWS S3, and finally uses the AWS SDK to invoke the ec2:TerminateInstances permission, physically deleting its own host server from your AWS account to immediately halt billing.

Master Server Self-Termination

The master EC2 instance (running the Django backend and Next.js frontend) runs a separate watchdog script. It continuously monitors if any Minecraft servers are running. If no Minecraft servers are active for 10 minutes, it:

  • Backs up the PostgreSQL database to S3
  • Backs up all world files to S3
  • Terminates itself to achieve true scale-to-zero billing (no cost when idle)

2. S3 State Hydration

Because the worker nodes are constantly being deleted, the architecture is completely stateless.

  • When a user clicks "Launch" on the Next.js frontend, Django triggers an AWS Lambda function (create_server).
  • Lambda provisions a fresh, blank Ubuntu EC2 instance and passes it a User-Data bootstrap script.
  • During boot, the EC2 instance connects to your secure AWS S3 Backup Bucket, downloads the specific world.zip associated with that server name, and injects it into the Docker volume mount.
  • This allows the game state to seamlessly persist across infinite server creations and deletions.

3. Infrastructure as Code (IaC)

The entire foundational cloud network (VPCs, Subnets, Internet Gateways, IAM Roles, RDS Databases, and S3 Buckets) is managed exclusively through Terraform.

  • Remote State Management: The spin_up.sh script dynamically creates a secure S3 bucket to store the terraform.tfstate file, ensuring the infrastructure deployment process is safe, tracked, and completely reproducible on any machine.
  • Dynamic Configuration: Once Terraform successfully provisions the network, Boto3 passes the new database credentials and IPs to Ansible, which automatically SSHs into the Master EC2 node to configure the Django and Next.js Docker containers.
🛟 Troubleshooting

Deployment fails immediately with an auth error

  • Double-check your AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY in aws_credentials.env. Make sure there are no trailing spaces.
  • Ensure the IAM user has programmatic access enabled and sufficient permissions (EC2, RDS, S3, Lambda, IAM).

Wrong region / resources created in unexpected location

  • Verify AWS_DEFAULT_REGION in aws_credentials.env matches the region shown in the top-right corner of your AWS console.

Terraform state corruption after an interrupted deployment

  • Never press Ctrl+C during deployment. If it happens, manually delete any partially created resources in the AWS console, then delete the squadhost-tfstate-<account-id> S3 bucket before re-running.

Server shows "Pending AWS IP..." for too long

  • EC2 instance provisioning and the Minecraft server startup can take 5–6 minutes. Wait it out before retrying.

Docker not found or permission denied

  • On Linux, ensure you ran sudo chmod 666 /var/run/docker.sock and that the Docker daemon is running (sudo systemctl start docker).