AWS to Mac Local Gateway

Infrastructure Documentation: AWS to Mac Local Gateway

Architecture Overview

This architecture utilizes a “Dumb Pipe” design. The AWS VPS acts strictly as a Layer 4 TCP proxy, blindly forwarding all web and SSH traffic through a secure Tailscale tunnel. All routing logic, SSL termination, and application hosting happen locally on the Mac hardware.

Phase 1: The AWS VPS (Edge Proxy)

The VPS is configured once and never touched again. It uses Nginx stream modules to pass raw TCP packets directly to the Tailscale IP.

1. Install Required Packages:

bash

sudo dnf install -y nginx nginx-mod-stream

2. Configure Nginx Master File: File: /etc/nginx/nginx.conf

nginx

user nginx;
worker_processes auto;
error_log /var/log/nginx/error.log notice;
pid /run/nginx.pid;

include /usr/share/nginx/modules/*.conf;

events {
    worker_connections 1024;
}

# STRICTLY LAYER 4 PASSTHROUGH
stream {
    # 1. HTTP Passthrough (Let's Encrypt & Initial Web)
    server {
        listen 80;
        proxy_pass 100.95.71.102:80;
    }

    # 2. HTTPS Passthrough (Secure Web)
    server {
        listen 443;
        proxy_pass 100.95.71.102:443;
    }

    # 3. Secure SSH Bouncer
    server {
        listen 2222;
        proxy_pass 100.95.71.102:22;
    }
}

3. AWS Security Group Requirements: Ensure the following Inbound Rules are open to 0.0.0.0/0:

HTTP: Port 80
HTTPS: Port 443
Custom TCP: Port 2222

Phase 2: The Mac Foundation (Local Router)

The Mac handles all incoming traffic, generating SSL certificates natively and routing traffic to Docker containers via a shared network.

1. Install Native Tools:

bash

brew install certbot

2. Prepare Directory Structure:

bash

mkdir -p ~/mac-gateway/conf.d
sudo mkdir -p /var/www/html
sudo chmod -R 755 /var/www/html

3. Deploy the Local Nginx Container: File: ~/mac-gateway/docker-compose.yml

yaml

services:
  local-nginx:
    image: nginx:alpine
    container_name: mac-local-router
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./conf.d:/etc/nginx/conf.d
      - /var/www/html:/var/www/html
      - /etc/letsencrypt:/etc/letsencrypt:ro
    networks:
      - project-network

networks:
  project-network:
    name: project-network
    driver: bridge

Run docker compose up -d to start the router.

Phase 3: The Playbook (Deploying a New Service)

Execute these steps entirely on the Mac whenever adding a new domain/service (e.g., rentcasa.com).

Step A: Connect the Application

Ensure the new application’s docker-compose.yml is attached to the shared network:

yaml

services:
  app-container:
    image: my-app
    networks:
      - project-network

networks:
  project-network:
    external: true

Step B: Create Initial HTTP Configuration

File: ~/mac-gateway/conf.d/rentcasa.com.conf

nginx

server {
    listen 80;
    server_name rentcasa.com www.rentcasa.com;

    # Allow Let's Encrypt validation
    location /.well-known/acme-challenge/ {
        root /var/www/html;
    }

    # Route traffic
    location / {
        proxy_pass http://app-container:3000;
        proxy_set_header Host $host;
    }
}

Reload: docker exec mac-local-router nginx -s reload

Step C: Generate SSL Certificate

Run natively on macOS:

bash

sudo certbot certonly --webroot -w /var/www/html -d rentcasa.com -d www.rentcasa.com

Step D: Lock Down HTTPS

Update ~/mac-gateway/conf.d/rentcasa.com.conf with the final secure configuration:

nginx

# Force HTTPS Redirect
server {
    listen 80;
    server_name rentcasa.com www.rentcasa.com;

    location /.well-known/acme-challenge/ {
        root /var/www/html;
    }

    location / {
        return 301 https://$host$request_uri;
    }
}

# Secure Application Block
server {
    listen 443 ssl;
    server_name rentcasa.com www.rentcasa.com;

    ssl_certificate /etc/letsencrypt/live/rentcasa.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/rentcasa.com/privkey.pem;

    location / {
        proxy_pass http://app-container:3000;
        proxy_set_header Host $host;
    }
}

Reload: docker exec mac-local-router nginx -s reload

Phase 4: CI/CD Pipeline (GitHub Actions)

Automate deployments from GitHub directly to the Mac via the AWS SSH tunnel.

1. Generate SSH Key on Mac:

bash

ssh-keygen -t ed25519 -C "github-actions"
cat ~/.ssh/id_ed25519.pub >> ~/.ssh/authorized_keys

2. Add GitHub Repository Secrets:

MAC_SSH_KEY: The contents of ~/.ssh/id_ed25519
AWS_HOST_IP: 13.204.230.168
MAC_USERNAME: Your Mac’s short username

3. GitHub Actions Workflow: File: .github/workflows/deploy.yml

yaml

name: Deploy to Home Server

on:
  push:
    branches:
      - main

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Execute Remote SSH Commands
        uses: appleboy/ssh-action@v1.0.3
        with:
          host: ${{ secrets.AWS_HOST_IP }}
          username: ${{ secrets.MAC_USERNAME }}
          key: ${{ secrets.MAC_SSH_KEY }}
          port: 2222
          script: |
            cd ~/projects/rentcasa
            git pull origin main
            docker compose up -d --build
            docker image prune -f