{"id":21491772,"url":"https://github.com/shotaromatsuya/minecraft-server-automation","last_synced_at":"2026-05-16T22:01:56.634Z","repository":{"id":183317866,"uuid":"669193108","full_name":"ShotaroMatsuya/minecraft-server-automation","owner":"ShotaroMatsuya","description":"Building minecraft server on ecs fargate via terraform","archived":false,"fork":false,"pushed_at":"2024-04-12T09:51:38.000Z","size":104964,"stargazers_count":1,"open_issues_count":30,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-04-13T22:20:37.261Z","etag":null,"topics":["docker","ecs-fargate","fluentbit","minecraft-server","terraform","tflint","tfsec"],"latest_commit_sha":null,"homepage":"","language":"HCL","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ShotaroMatsuya.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-07-21T15:12:37.000Z","updated_at":"2024-07-15T08:00:19.878Z","dependencies_parsed_at":"2023-09-25T20:37:20.823Z","dependency_job_id":"71ed3466-9c59-42ee-a4d0-52bcf4e06abb","html_url":"https://github.com/ShotaroMatsuya/minecraft-server-automation","commit_stats":null,"previous_names":["shotaromatsuya/minecraft-server-automation"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShotaroMatsuya%2Fminecraft-server-automation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShotaroMatsuya%2Fminecraft-server-automation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShotaroMatsuya%2Fminecraft-server-automation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ShotaroMatsuya%2Fminecraft-server-automation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ShotaroMatsuya","download_url":"https://codeload.github.com/ShotaroMatsuya/minecraft-server-automation/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244022635,"owners_count":20385133,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","ecs-fargate","fluentbit","minecraft-server","terraform","tflint","tfsec"],"created_at":"2024-11-23T15:19:16.088Z","updated_at":"2026-05-16T22:01:51.596Z","avatar_url":"https://github.com/ShotaroMatsuya.png","language":"HCL","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Static Badge](https://img.shields.io/badge/minecraft-v1.21-blue)\n[![drift](https://github.com/ShotaroMatsuya/minecraft-server-automation/actions/workflows/drift.yml/badge.svg)](https://github.com/ShotaroMatsuya/minecraft-server-automation/actions/workflows/drift.yml)\n[![Matrix Docker Build with Snyk Scan](https://github.com/ShotaroMatsuya/minecraft-server-automation/actions/workflows/build_image.yml/badge.svg)](https://github.com/ShotaroMatsuya/minecraft-server-automation/actions/workflows/build_image.yml)\n[![Start and Stop Workflow](https://github.com/ShotaroMatsuya/minecraft-server-automation/actions/workflows/schedule_job.yml/badge.svg)](https://github.com/ShotaroMatsuya/minecraft-server-automation/actions/workflows/schedule_job.yml)\n[![Terragrunt PR Check](https://github.com/ShotaroMatsuya/minecraft-server-automation/actions/workflows/terragrunt-pr-check.yml/badge.svg)](https://github.com/ShotaroMatsuya/minecraft-server-automation/actions/workflows/terragrunt-pr-check.yml)\n\n# Minecraft Server Automation with CI/CD\n\n\u003c!-- Test: Verify label-based environment targeting works with string outputs --\u003e\n\u003c!-- Test case: target:keeping label should trigger apply workflow --\u003e\n\u003c!-- Final verification: Hotfix PR #329 apply workflow fixes --\u003e\n\nCost-optimized Minecraft server infrastructure using **Terragrunt** for multi-environment management and automated CI/CD.\n\n## 🏗️ Architecture Overview\n\nThis infrastructure is divided into two environments to optimize costs and maintainability:\n\n### keeping\nResources that do not cost much even if they are constantly running:\n- **VPC \u0026 Networking**: Subnets, Security Groups, NAT Gateway\n- **IAM Roles \u0026 Policies**: Service authentication and permissions\n- **SNS Topics**: Notification channels for monitoring\n\n### scheduling\nCost-optimized resources that automatically start/stop daily:\n- **ECS Cluster \u0026 Service**: Minecraft server container\n- **Lambda Functions**: Automation and scheduling\n- **CloudWatch**: Monitoring and alerting\n\n```mermaid\ngraph TB\n    subgraph \"AWS Infrastructure\"\n        subgraph \"keeping (Always On)\"\n            VPC[VPC \u0026 Networking]\n            IAM[IAM Roles]\n            SNS[SNS Topics]\n        end\n        \n        subgraph \"scheduling (Cost Optimized)\"\n            ECS[ECS Cluster]\n            Lambda[Lambda Functions]\n            CW[CloudWatch]\n        end\n        \n        subgraph \"Storage \u0026 Backup\"\n            S3[S3 Bucket]\n            EFS[EFS Volume]\n        end\n        \n        subgraph \"CI/CD Pipeline\"\n            GHA[GitHub Actions]\n            TG[Terragrunt]\n            Docker[Docker Hub]\n        end\n    end\n    \n    subgraph \"External\"\n        Players[Minecraft Players]\n        Slack[Slack Notifications]\n    end\n    \n    Players --\u003e ECS\n    ECS --\u003e EFS\n    ECS --\u003e S3\n    Lambda --\u003e ECS\n    CW --\u003e SNS\n    SNS --\u003e Slack\n    GHA --\u003e TG\n    TG --\u003e VPC\n    TG --\u003e ECS\n    Docker --\u003e ECS\n```\n\n![Infrastructure Diagram](./docs/mc-server.drawio.png)\n\n## ✨ Main Features\n\n### 🔄 Automated Backup \u0026 Restore\nBy customizing the entrypoint shell of the Dockerfile, it is possible to restore from the latest data from backup (S3) when starting, and automatically back up when stopping. Continuous backups to inexpensive object storage (AWS S3) eliminate the risk of data loss due to frequent container lifecycles. Those activities will be notified in your Slack channel.\n\n### 📋 Task Definition Mapped from YAML\nImproves operability by defining container environment variables in multiple YAML files and mapping them with Terragrunt. This allows for easy configuration management across different environments.\n\n### ⏰ Time Travel Restore\nBy default, restore is performed from the latest backup when the container starts. It is also possible to restore world data from a specific recovery point via Terragrunt variables. This is useful when you want to travel back in time to your precious world.\n\n### 🚀 GitHub Actions CI/CD\n\n- **Label-Based Environment Targeting**: Automatically detects infrastructure changes and applies appropriate labels (`target:keeping`, `target:scheduling`) for environment-specific deployment\n- **Manual Label Override**: Manually apply labels to force deployment even without infrastructure changes (useful for configuration updates or emergency deployments)\n- **Enhanced PR Validation**: Detailed Terragrunt plan output with resource counting\n- **Security Scanning**: Trivy SAST analysis with SARIF reporting\n- **Comment Management**: Prevents PR spam with comment updates\n- **AWS OIDC**: Secure authentication without long-lived credentials\n\n### 🏷️ PR Label System\n\nThe project uses an intelligent labeling system to control which environments are affected by changes:\n\n#### Automatic Labels\n\n- **`target:keeping`**: Automatically applied when changes affect keeping environment files\n- **`target:scheduling`**: Automatically applied when changes affect scheduling environment files\n\n#### Manual Labels\n\n- **`target:keeping`**: Manually apply to force keeping environment deployment\n- **`target:scheduling`**: Manually apply to force scheduling environment deployment  \n- **`no-apply`**: Prevent any apply operations (useful for testing or documentation changes)\n\n#### Label Behavior\n\n```bash\n# Files changed: terragrunt/environments/keeping/\n# → Automatically adds: target:keeping\n\n# Files changed: terragrunt/environments/scheduling/\n# → Automatically adds: target:scheduling\n\n# Manual label added: target:scheduling\n# → Forces scheduling apply even without file changes\n\n# Manual label added: no-apply\n# → Prevents all applies regardless of changes\n```\n\n#### Workflow Triggers\n\n- **PR Checks**: Run only for environments with `target:*` labels\n- **Apply Operations**: Execute only for labeled environments after merge\n- **Comment System**: Report results only for executed environments\n\n## 🎯 Dispatch Workflows\n\nAdvanced Minecraft world management via GitHub webhook triggers:\n\n### Restore World from Backup\n\nRestores Minecraft world from a specific backup file:\n\n```bash\ncurl -X POST \\\n  -H \"Accept: application/vnd.github.v3+json\" \\\n  -H \"Authorization: token $GITHUB_TOKEN\" \\\n  https://api.github.com/repos/YOUR_OWNER/YOUR_REPO/dispatches \\\n  -d '{\n    \"event_type\": \"restore-and-set-recoverypoint\",\n    \"client_payload\": {\n      \"recovery_file\": \"world-backup-20241201-120000.tar.gz\"\n    }\n  }'\n```\n\n### Create New World with Seed\n\nCreates a new Minecraft world with specified seed value:\n\n```bash\ncurl -X POST \\\n  -H \"Accept: application/vnd.github.v3+json\" \\\n  -H \"Authorization: token $GITHUB_TOKEN\" \\\n  https://api.github.com/repos/YOUR_OWNER/YOUR_REPO/dispatches \\\n  -d '{\n    \"event_type\": \"create-and-set-seed\",\n    \"client_payload\": {\n      \"seed_value\": \"1234567890\"\n    }\n  }'\n```\n\n**Features:**\n\n- 🔄 Automated ECS service restart\n- 📢 Slack notifications\n- ☁️ AWS OIDC authentication\n- 🏗️ Terragrunt-based deployment\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n```bash\n# Install aqua for tool management\ncurl -sSfL https://raw.githubusercontent.com/aquaproj/aqua-installer/v3.1.0/aqua-installer | bash\nexport PATH=\"${AQUA_ROOT_DIR:-${XDG_DATA_HOME:-$HOME/.local/share}/aqua}/bin:$PATH\"\n\n# Install tools\nmake install-tools\n```\n\n### Deploy\n\n```bash\n# Configure AWS\nexport AWS_ACCOUNT_ID=your-account-id\naws configure\n\n# Deploy infrastructure\nmake tg-init\nmake tg-deploy-all\n\n# Start server\nmake tg-start-minecraft\n```\n\n## 📋 Commands\n\n| Command | Description |\n|---------|-------------|\n| `make tg-deploy-all` | Deploy all environments |\n| `make tg-start-minecraft` | Start Minecraft server |\n| `make tg-stop-minecraft` | Stop Minecraft server |\n| `make tg-destroy-all` | Destroy all infrastructure |\n| `make tg-plan-all` | Plan changes for all environments |\n| `make tg-validate` | Validate Terragrunt configuration |\n| `make install-tools` | Install development tools via aqua |\n\nRun `make help` for the full command list.\n\n## 🔧 AWS Setup\n\nSee [AWS OIDC Setup Guide](docs/aws-oidc-setup.md) for GitHub Actions authentication configuration.\n\n## 🛠️ Utilities\n\n### Simple Load Test\n\nCPU load by repeatedly hitting the yes command:\n\n```bash\nyes \u003e /dev/null \u0026\nyes \u003e /dev/null \u0026\nyes \u003e /dev/null \u0026\nyes \u003e /dev/null \u0026\nyes \u003e /dev/null \u0026\n```\n\nCheck running processes:\n```bash\n$ jobs\n[1]   実行中               yes \u003e /dev/null \u0026\n[2]   実行中               yes \u003e /dev/null \u0026\n[3]   実行中               yes \u003e /dev/null \u0026\n[4]   実行中               yes \u003e /dev/null \u0026\n[5]   実行中               yes \u003e /dev/null \u0026\n```\n\nKill processes:\n```bash\n$ kill %1 %2 %3\n[1] 終了しました yes \u003e /dev/null\n[2]- 終了しました yes \u003e /dev/null\n[3]+ 終了しました yes \u003e /dev/null\n```\n\n### Memory Load Test\n\nProcess that consumes 500MB of memory for each press of Enter:\n\n```bash\n#!/bin/bash\n# load-memory.sh\n# \"--bytes 5000000\" is 500MB.\necho PID=$$\necho -n \"[ Enter : powerup! ] , [ Ctrl+d : stop ]\"\nc=0\nwhile read byte; do\n   eval a$c'=$(head --bytes 5000000 /dev/zero |cat -v)'\n   c=$(($c+1))\n   echo -n \"\u003e\"\ndone\necho\n```\n\nRun the script:\n```bash\nchmod +x load-memory.sh\n./load-memory.sh\n```\n\n### Bulk Deletion of All Backup Vaults\n\n```bash\naws backup list-backup-jobs | jq -r '.BackupJobs[] | select(.BackupVaultName == \"minecraft-vault\" )' | jq -r '.RecoveryPointArn' | xargs -L 1 aws backup delete-recovery-point --backup-vault-name minecraft-vault --recovery-point-arn\n```\n\n### ECS Exec Execution\n\n```bash\ncl=$(aws ecs list-clusters | jq -r '.clusterArns[0]' )\nprefix=`echo ${cl} | sed -E 's/.+cluster\\///g' `\ntaskarn=$(aws ecs list-tasks --cluster ${cl} | jq -r '.taskArns[0]')\ntaskid=`echo ${taskarn} | sed -E 's/.+task\\/.+\\///g' `\nCONTAINER_NAME=\"minecraft\"\n\necho ${cl}\necho ${prefix}\necho ${taskarn}\necho ${taskid}\necho ${CONTAINER_NAME}\n\naws ecs execute-command \\\n --region ap-northeast-1 \\\n --cluster ${cl} \\\n --task ${taskarn} \\\n --container ${CONTAINER_NAME} \\\n --command \"/bin/sh\" \\\n --interactive\n```\n\n### Confirm Environment Variables Locally\n\n```bash\ndocker compose run --rm mc env\n```\n\n## 🏷️ Technology Stack\n\n- **Infrastructure as Code**: Terragrunt 0.67.16 + Terraform 1.9.8\n- **Container Orchestration**: AWS ECS with Fargate\n- **CI/CD**: GitHub Actions with AWS OIDC\n- **Security**: Trivy SAST scanning, TFLint validation\n- **Monitoring**: CloudWatch + SNS + Slack integration\n- **Tool Management**: aqua package manager\n- **Code Quality**: ShellCheck, actionlint\n\n## 📊 Cost Optimization\n\nThis infrastructure is designed with cost optimization in mind:\n\n1. **Scheduled Start/Stop**: Automatically starts at 19:00 JST and stops at 01:00 JST\n2. **Spot Instances**: Uses EC2 Spot pricing where possible\n3. **Efficient Storage**: EFS for persistent world data, S3 for backups\n4. **Resource Separation**: Critical infrastructure (`keeping`) vs. workload (`scheduling`)\n\n### 💰 Monthly Cost Breakdown\n\n| Resource Type | Environment | Specifications | Hours/Month | Unit Price | Monthly Cost (USD) |\n|---------------|-------------|----------------|-------------|------------|-------------------|\n| **💻 ECS Fargate** | scheduling | 2048 CPU, 4096 MB RAM | 186h | $0.04048/h | $7.53 |\n| **🌐 Network Load Balancer** | scheduling | 2 ports (25565, 8080) | 744h | $0.0225/h | $16.74 |\n| **📊 CloudWatch Logs** | scheduling | ~5GB/month | - | $0.50/GB | $2.50 |\n| **🔔 SNS** | keeping | Notification service | - | $0.50/1M | $0.01 |\n| **💬 AWS Chatbot** | keeping | Slack integration | - | Free | $0.00 |\n| **🔑 IAM** | keeping | Roles \u0026 policies | - | Free | $0.00 |\n| **🌐 VPC** | keeping | Subnets \u0026 security groups | - | Free | $0.00 |\n| **🎯 Lambda** | scheduling | Log processing \u0026 notifications | 100 calls/month | $0.20/1M | $0.01 |\n| **🗄️ ECR** | keeping | Container image storage | 2GB | $0.10/GB | $0.20 |\n| **📱 Route 53** | scheduling | Domain management | 1 domain | $0.50/month | $0.50 |\n| **🔐 ACM Certificate** | scheduling | SSL certificate | - | Free | $0.00 |\n| **💾 S3** | keeping | Backup storage (10GB) | - | $0.023/GB | $0.23 |\n\n#### 📈 Cost Summary\n\n| Category | Monthly Cost (USD) | Percentage |\n|----------|-------------------|------------|\n| **🔄 Variable Costs (scheduling)** | $27.28 | 98.2% |\n| **⚡ Fixed Costs (keeping)** | $0.44 | 1.8% |\n| **🎯 Total** | **$27.72** | 100% |\n\n#### ⏰ Operation Schedule Details\n\n- **Operating Hours**: 19:00-01:00 JST (6 hours/day)\n- **Monthly Runtime**: 6h × 31 days = 186 hours/month\n- **Cost Savings**: ~75% reduction compared to 24/7 operation\n\n#### 💡 Cost Optimization Highlights\n\n1. **🕒 Scheduled Operation**: 75% cost reduction through night-only operation\n2. **🎯 Future Spot Instances**: Potential 70% additional savings with Fargate Spot\n3. **📦 EFS Optimization**: Currently disabled to reduce costs\n4. **🗂️ Log Management**: Optimized CloudWatch Logs retention\n\n\u003e **Note**: Costs are based on ap-northeast-1 (Tokyo) region pricing and may vary based on actual usage patterns, data transfer, and log volume.\n\n## 🔒 Security Features\n\n- **AWS OIDC Authentication**: No long-lived credentials in GitHub\n- **SAST Scanning**: Trivy security analysis on every PR\n- **Least Privilege IAM**: Minimal required permissions\n- **Encrypted Storage**: EFS and S3 encryption at rest\n- **Network Security**: VPC with security groups\n\n## 📝 Development\n\nThis project uses:\n\n- **aqua**: Tool version management\n- **pre-commit**: Git hooks for code quality\n- **GitHub Actions**: Automated testing and deployment\n- **Terragrunt**: DRY infrastructure management\n\nFor development setup, see the [Development Guide](docs/development.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshotaromatsuya%2Fminecraft-server-automation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshotaromatsuya%2Fminecraft-server-automation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshotaromatsuya%2Fminecraft-server-automation/lists"}