diff --git a/modules/20-services-apps/pterodactyl/README.md b/modules/20-services-apps/pterodactyl/README.md new file mode 100644 index 0000000..802b1e7 --- /dev/null +++ b/modules/20-services-apps/pterodactyl/README.md @@ -0,0 +1,101 @@ +# Pterodactyl Module + +This module is a parent module for deploying the [Pterodactyl](https://pterodactyl.io/) game server management system, which consists of multiple components: + +1. **Panel** - The web-based administration interface and API server +2. **Wings** - The game server agent that controls individual game servers + +## Overview + +The Pterodactyl module consists of two submodules: + +- `panel` - Deploys the Pterodactyl control panel with its database and cache servers +- `wings` - Deploys the Pterodactyl Wings agent for running game servers + +For a complete installation, both components should be deployed. + +## Architecture + +Pterodactyl is designed with a client-server architecture: + +- **Panel (Server)**: The central management interface where administrators create servers, manage users, and configure settings. +- **Wings (Agent)**: Installed on each machine that will run game servers, communicates with the Panel via API. + +In a homelab environment, you might deploy both components on the same machine or separate them for better resource allocation. + +## Usage + +### Deploying Both Components + +```hcl +module "pterodactyl_panel" { + source = "./modules/20-services-apps/pterodactyl/panel" + volume_path = "${var.volume_host}/pterodactyl/panel" + networks = [module.services.homelab_docker_network_name] +} + +module "pterodactyl_wings" { + source = "./modules/20-services-apps/pterodactyl/wings" + volume_path = "${var.volume_host}/pterodactyl/wings" + networks = [module.services.homelab_docker_network_name] +} + +# Include both service definitions in your networking modules +module "services" { + source = "./modules/services" + # ... + service_definitions = [ + module.pterodactyl_panel.service_definition, + module.pterodactyl_wings.service_definition, + # Other service definitions + ] +} +``` + +## Configuration Requirements + +### Panel Setup + +1. Create a `.env` file in the panel module directory with required variables: + - Database credentials (`MYSQL_PASSWORD`, `MYSQL_ROOT_PASSWORD`, etc.) + - App settings (`APP_URL`, `APP_TIMEZONE`, etc.) + - CORS and proxy settings + +2. SMTP settings are sourced from the global SMTP module + +### Wings Setup + +1. After deploying the Panel, you need to: + - Create a node in the Panel UI + - Download the wings configuration from the Panel + - Place it at `${volume_path}/etc/config.yml` for the Wings module + +## Network Configuration + +Both components create their own dedicated Docker networks: + +- `ptero-panel`: For communication between Panel, database, and cache +- `ptero-wings`: For communication between Wings and game servers + +Additionally, both components need to be connected to your main homelab network to communicate with each other. + +## Service Definitions + +Both components generate service definitions that can be used by your networking modules: + +- Panel: Published on the domain `gameservers.yourdomain.com` +- Wings: Published on the domain `wings.yourdomain.com` + +## Security Considerations + +- Wings requires `privileged` mode to create game server containers +- Panel communicates with Wings via API using a token configured in the wings config.yml + +## Additional Documentation + +For more detailed information about each component, please see: + +- [Panel README](/modules/20-services-apps/pterodactyl/panel/README.md) +- [Wings README](/modules/20-services-apps/pterodactyl/wings/README.md) + +For official Pterodactyl documentation, visit [https://pterodactyl.io/](https://pterodactyl.io/) diff --git a/modules/20-services-apps/pterodactyl/panel/README.md b/modules/20-services-apps/pterodactyl/panel/README.md new file mode 100644 index 0000000..4bbc0ee --- /dev/null +++ b/modules/20-services-apps/pterodactyl/panel/README.md @@ -0,0 +1,109 @@ +# Pterodactyl Panel Module + +This module deploys [Pterodactyl Panel](https://pterodactyl.io/), a game server management panel, as Docker containers in the homelab environment. + +## Overview + +The Pterodactyl Panel module: + +- Deploys three Docker containers: + - `pterodactyl-panel`: The main web UI and API server + - `pterodactyl-db`: A MariaDB database backend + - `pterodactyl-cache`: A Redis cache server +- Creates a dedicated Docker network (`ptero-panel`) for container communication +- Persists data to volumes on the host +- Provides service definition for integration with networking modules + +## Usage + +```hcl +module "pterodactyl_panel" { + source = "./modules/20-services-apps/pterodactyl/panel" + volume_path = "/path/to/volumes/pterodactyl/panel" + networks = ["homelab-network"] +} +``` + +## Variables + +| Variable | Description | Type | Default | +| ------------- | ---------------------------------------------------------- | -------------- | ---------- | +| `image_tag` | Tag of the Pterodactyl Panel image to use | `string` | `"latest"` | +| `volume_path` | Host path for Pterodactyl Panel volumes | `string` | - | +| `networks` | List of networks to which the panel should be attached | `list(string)` | `[]` | + +## Outputs + +| Output | Description | +| -------------------- | ---------------------------------------------------------- | +| `service_definition` | Service definition for integration with networking modules | + +## Service Definition + +This module outputs a service definition that is used by the networking modules to expose the service. + +```hcl +{ + name = "pterodactyl-panel" + primary_port = 80 + endpoint = "http://pterodactyl-panel:80" + subdomains = ["gameservers"] + publish_via = "tunnel" +} +``` + +## Environment Variables + +Pterodactyl Panel requires several environment variables to function properly. These are stored in a `.env` file in the module directory and read using the `dotenv` Terraform provider. Key variables include: + +- Panel Configuration: + - `APP_URL`: The URL where the panel will be accessed + - `APP_TIMEZONE`: The timezone for the application + - `APP_SERVICE_AUTHOR`: Service author information + +- Database Configuration: + - `MYSQL_PASSWORD`: Database password + - `MYSQL_ROOT_PASSWORD`: Database root password + - `MYSQL_DATABASE`: Database name + - `MYSQL_USER`: Database username + +- Mail Configuration: + - Mail settings are automatically sourced from the global SMTP module + +## Data Persistence + +Pterodactyl Panel stores its data in multiple volumes: + +1. Application data: `/app/var` in the container, mapped to `${volume_path}/var` on the host +2. Nginx configuration: `/etc/nginx/http.d` in the container, mapped to `${volume_path}/nginx` on the host +3. SSL certificates: `/etc/letsencrypt` in the container, mapped to `${volume_path}/certs` on the host +4. Logs: `/app/storage/logs` in the container, mapped to `${volume_path}/logs` on the host +5. Database data: `/var/lib/mysql` in the MariaDB container, mapped to `${volume_path}/database` on the host + +## Networking + +The module creates a dedicated Docker network named `ptero-panel` for communication between the panel, database, and cache containers. The panel container is also attached to any additional networks specified in the `networks` variable, allowing it to communicate with other services in the homelab. + +## Integration with Networking Modules + +This service is configured to be exposed through a Cloudflare tunnel for secure remote access, set by `publish_via = "tunnel"`. + +## Example Integration in Main Configuration + +```hcl +module "pterodactyl_panel" { + source = "./modules/20-services-apps/pterodactyl/panel" + volume_path = module.system_globals.volume_host + networks = [module.services.homelab_docker_network_name] +} + +# The service definition is automatically included in the services output +module "services" { + source = "./modules/services" + # ... + service_definitions = [ + module.pterodactyl_panel.service_definition, + # Other service definitions + ] +} +``` diff --git a/modules/20-services-apps/pterodactyl/panel/main.tf b/modules/20-services-apps/pterodactyl/panel/main.tf index b5c706f..fb9c3d5 100644 --- a/modules/20-services-apps/pterodactyl/panel/main.tf +++ b/modules/20-services-apps/pterodactyl/panel/main.tf @@ -159,5 +159,6 @@ output "service_definition" { primary_port = 80 endpoint = "http://${local.container_name}:80" subdomains = ["gameservers"] + publish_via = "tunnel" } } diff --git a/modules/20-services-apps/pterodactyl/wings/README.md b/modules/20-services-apps/pterodactyl/wings/README.md new file mode 100644 index 0000000..99969bc --- /dev/null +++ b/modules/20-services-apps/pterodactyl/wings/README.md @@ -0,0 +1,100 @@ +# Pterodactyl Wings Module + +This module deploys [Pterodactyl Wings](https://pterodactyl.io/wings/), the game server agent component of Pterodactyl, as a Docker container in the homelab environment. + +## Overview + +The Pterodactyl Wings module: + +- Deploys the `pterodactyl-wings` Docker container +- Creates a dedicated Docker network (`ptero-wings`) for game server communication +- Persists data to volumes on the host +- Provides service definition for integration with networking modules +- Runs with privileged mode to manage game server containers + +## Usage + +```hcl +module "pterodactyl_wings" { + source = "./modules/20-services-apps/pterodactyl/wings" + volume_path = "/path/to/volumes/pterodactyl/wings" + networks = ["homelab-network"] +} +``` + +## Variables + +| Variable | Description | Type | Default | +| ------------- | ------------------------------------------------------- | -------------- | ----------- | +| `image_tag` | Tag of the Pterodactyl Wings image to use | `string` | `"v1.11.3"` | +| `volume_path` | Host path for Pterodactyl Wings volumes | `string` | - | +| `networks` | List of networks to which wings should be attached | `list(string)` | `[]` | + +## Outputs + +| Output | Description | +| -------------------- | ---------------------------------------------------------- | +| `service_definition` | Service definition for integration with networking modules | + +## Service Definition + +This module outputs a service definition that is used by the networking modules to expose the service. + +```hcl +{ + name = "pterodactyl-wings" + primary_port = 443 + endpoint = "http://pterodactyl-wings:443" + subdomains = ["wings"] + publish_via = "tunnel" +} +``` + +## Environment Variables + +Pterodactyl Wings uses the following environment variables: + +- `TZ`: Timezone (set to Australia/Brisbane) +- `WINGS_UID`: User ID for wings process (988) +- `WINGS_GID`: Group ID for wings process (988) +- `WINGS_USERNAME`: Username for wings process ("pterodactyl") + +## Data Persistence + +Pterodactyl Wings uses several volume mounts: + +1. Docker socket: `/var/run/docker.sock` (for controlling game server containers) +2. Docker containers: `/var/lib/docker/containers/` (for accessing container information) +3. SSL certificates: `/etc/ssl/certs` (mounted read-only) +4. Wings configuration: `/etc/pterodactyl/` in the container, mapped to `${volume_path}/etc` +5. Wings data: `/var/lib` in the container, mapped to `${volume_path}/var/lib` +6. Logs: `/var/log/pterodactyl/` in the container, mapped to `${volume_path}/var/log` +7. Temporary files: `${volume_path}/tmp` in the container and host + +## Networking + +The module creates a dedicated Docker network named `ptero-wings` for game server communication. This network is configured with the subnet `172.21.0.0/16` and is made attachable to allow game server containers to connect to it. The wings container is also attached to any additional networks specified in the `networks` variable. + +## Integration with Networking Modules + +This service is configured to be exposed through a Cloudflare tunnel for secure remote access, set by `publish_via = "tunnel"`. + +## Example Integration in Main Configuration + +```hcl +module "pterodactyl_wings" { + source = "./modules/20-services-apps/pterodactyl/wings" + volume_path = module.system_globals.volume_host + networks = [module.services.homelab_docker_network_name] +} + +# The service definition is automatically included in the services output +module "services" { + source = "./modules/services" + # ... + service_definitions = [ + module.pterodactyl_wings.service_definition, + # Other service definitions + ] +} +``` diff --git a/modules/20-services-apps/pterodactyl/wings/main.tf b/modules/20-services-apps/pterodactyl/wings/main.tf index 42b02bb..51a1984 100644 --- a/modules/20-services-apps/pterodactyl/wings/main.tf +++ b/modules/20-services-apps/pterodactyl/wings/main.tf @@ -113,5 +113,6 @@ output "service_definition" { primary_port = 443 endpoint = "http://${local.container_name}:443" subdomains = local.subdomains + publish_via = "tunnel" } }