HotaruBlaze/homelab-opentofu
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(pterodactyl): define publish_via config

Browse Source
This commit is contained in:
Yuris Cakranegara
2025-06-12 21:39:58 +10:00
parent e4ecd6dbcf
commit 6709c85b0e
5 changed files with 312 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
modules/20-services-apps/pterodactyl/README.md Normal file
View File

@@ -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/)

109
modules/20-services-apps/pterodactyl/panel/README.md Normal file
View File

@@ -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
]
}
```

1
modules/20-services-apps/pterodactyl/panel/main.tf
View File

@@ -159,5 +159,6 @@ output "service_definition" {
primary_port = 80
endpoint = "http://${local.container_name}:80"
subdomains = ["gameservers"]
publish_via = "tunnel"
}
}

100
modules/20-services-apps/pterodactyl/wings/README.md Normal file
View File

@@ -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
]
}
```

1
modules/20-services-apps/pterodactyl/wings/main.tf
View File

@@ -113,5 +113,6 @@ output "service_definition" {
primary_port = 443
endpoint = "http://${local.container_name}:443"
subdomains = local.subdomains
publish_via = "tunnel"
}
}