https://github.com/floryn08/valheim-server-discord-bot
A Discord bot that controls your valheim deployment to start and close the server container on demand.
https://github.com/floryn08/valheim-server-discord-bot
discord docker docker-compose helm k8s portainer portainer-api valheim
Last synced: 3 months ago
JSON representation
A Discord bot that controls your valheim deployment to start and close the server container on demand.
- Host: GitHub
- URL: https://github.com/floryn08/valheim-server-discord-bot
- Owner: floryn08
- Created: 2024-02-05T15:06:35.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2026-03-03T08:37:50.000Z (3 months ago)
- Last Synced: 2026-03-03T11:49:16.572Z (3 months ago)
- Topics: discord, docker, docker-compose, helm, k8s, portainer, portainer-api, valheim
- Language: TypeScript
- Homepage:
- Size: 1.39 MB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# Valheim Server Discord Bot
A Discord bot that manages your game servers (Valheim, Terraria, etc.) using either Docker or Kubernetes.
This approach minimizes resource consumption since many game server docker images don't support auto pausing the server when there are no players on the server.
The bot registers 3 slash commands:
- `/start ` - Start a game server
- `/stop ` - Stop a game server
- `/status ` - Check a game server's status
Each command includes autocomplete suggestions for available servers.
## Runtime Modes
The bot supports two runtime modes:
- **kubernetes**: Manages Valheim servers running as Kubernetes deployments
- **docker**: Manages Valheim servers running as Docker containers
Set the runtime mode using the `RUNTIME_MODE` environment variable (defaults to `kubernetes`).
## How to run
### With Kubernetes
#### Prerequisites
- A Kubernetes cluster
- `kubectl` configured to access your cluster
- Helm 3 installed
- (Optional) HashiCorp Vault for secret management
#### Installation Steps
1. **Invite your bot to a Discord server**
- Use the OAuth2 URL Generator from https://discord.com/developers/applications
- Select the required bot permissions
2. **Install using Helm**
```bash
# Navigate to the helm chart directory
cd deployment/helm
# Install the chart
helm install valheim-bot . -n game-servers --create-namespace
```
3. **Configure the bot**
The Helm chart supports two configuration methods:
**Option A: Using ConfigMap (for non-sensitive data)**
Edit the ConfigMap after installation:
```bash
kubectl edit configmap valheim-bot-discord-bot -n game-servers
```
Set the following environment variables:
- `RUNTIME_MODE`: Set to `kubernetes` (default)
- `DISCORD_TOKEN`: Your Discord bot token
- `DISCORD_CLIENT_ID`: Your Discord application client ID
- `GUILD_IDS`: Comma-separated list of Discord server IDs
- `NAMESPACE`: The namespace where your game servers run (defaults to the chart namespace)
- `SERVERS`: JSON array of server configurations (see below)
- `JOIN_CODE_LOOP_COUNT`: (Optional) Number of retries for join code (default: 20)
- `JOIN_CODE_LOOP_TIMEOUT_MILLIS`: (Optional) Timeout in milliseconds (default: 5000)
**SERVERS Configuration Format:**
```json
[
{
"id": "valheim",
"resourceName": "valheim-deployment",
"resourceType": "deployment",
"containerName": "valheim-container",
"serverName": "My Valheim Server",
"startedLogPattern": "Session \"My Valheim Server\" with join code",
"joinCodeWordIndex": 5
},
{
"id": "terraria",
"resourceName": "terraria-statefulset",
"resourceType": "statefulset",
"containerName": "terraria-container",
"serverName": "My Terraria Server",
"startedLogPattern": "Server started"
}
]
```
- `id`: Unique identifier for the server (shown in Discord autocomplete)
- `resourceName`: Kubernetes resource name - deployment or statefulset (required for Kubernetes mode)
- `resourceType`: Type of Kubernetes resource - `deployment` (default) or `statefulset` (optional)
- `containerName`: Docker container name (required for Docker mode)
- `serverName`: Display name for the server (used in messages)
- `startedLogPattern`: Pattern to search for in logs to detect server has started
- `joinCodeWordIndex`: (Optional) Word index to extract join code from matched log line
**Option B: Using HashiCorp Vault (recommended for production)**
If you have Vault enabled (`vault.enabled: true` in values.yaml):
- Store secrets in Vault at path: `kv/game-servers/valheim-bot-discord-bot`
- The chart will automatically create a VaultStaticSecret resource
4. **Customize the deployment**
Create a custom `values.yaml`:
```yaml
namespace: game-servers
discordBotImage: ghcr.io/floryn08/valheim-server-discord-bot:1.2.0
vault:
enabled: false # Set to true if using Vault
```
Install with custom values:
```bash
helm install valheim-bot . -f custom-values.yaml -n game-servers --create-namespace
```
5. **Verify the deployment**
```bash
kubectl get pods -n game-servers
kubectl logs -f deployment/valheim-bot-discord-bot -n game-servers
```
#### Upgrading
To upgrade to a new version:
```bash
helm upgrade valheim-bot . -n game-servers
```
#### Uninstalling
To remove the deployment:
```bash
helm uninstall valheim-bot -n game-servers
```
### With Docker
#### Prerequisites
- Docker installed and running
- A running game server container
- Discord bot credentials
#### Installation Steps
1. **Invite your bot to a Discord server**
- Use the OAuth2 URL Generator from https://discord.com/developers/applications
- Select the required bot permissions
2. **Create a `.env` file (for local development)**
```env
RUNTIME_MODE=docker
DISCORD_TOKEN=your_discord_bot_token
DISCORD_CLIENT_ID=your_discord_client_id
GUILD_IDS=your_guild_id1,your_guild_id2
SERVERS='[{"id":"valheim","resourceName":"valheim-deployment","containerName":"valheim-container","serverName":"My Valheim Server","startedLogPattern":"Session \"My Valheim Server\" with join code","joinCodeWordIndex":5}]'
# Optional
# DOCKER_SOCKET_PATH=/var/run/docker.sock
# JOIN_CODE_LOOP_COUNT=20
# JOIN_CODE_LOOP_TIMEOUT_MILLIS=5000
```
**Environment Variables for Docker Mode:**
- `RUNTIME_MODE`: Set to `docker`
- `DISCORD_TOKEN`: Your Discord bot token
- `DISCORD_CLIENT_ID`: Your Discord application client ID
- `GUILD_IDS`: Comma-separated list of Discord server IDs
- `SERVERS`: JSON array of server configurations (see Kubernetes section for format)
- `DOCKER_SOCKET_PATH`: (Optional) Path to Docker socket (default: `/var/run/docker.sock`)
- `JOIN_CODE_LOOP_COUNT`: (Optional) Number of retries for join code (default: 20)
- `JOIN_CODE_LOOP_TIMEOUT_MILLIS`: (Optional) Timeout in milliseconds (default: 5000)
3. **Run with Docker Compose**
Update the provided `deployment/docker-compose.yaml` or create your own:
```yaml
services:
valheim-server-discord-bot:
container_name: valheim-server-discord-bot
image: ghcr.io/floryn08/valheim-server-discord-bot:latest
environment:
RUNTIME_MODE: docker
DISCORD_TOKEN: ${DISCORD_TOKEN}
DISCORD_CLIENT_ID: ${DISCORD_CLIENT_ID}
GUILD_IDS: ${GUILD_IDS}
SERVERS: ${SERVERS}
JOIN_CODE_LOOP_COUNT: ${JOIN_CODE_LOOP_COUNT:-20}
JOIN_CODE_LOOP_TIMEOUT_MILLIS: ${JOIN_CODE_LOOP_TIMEOUT_MILLIS:-5000}
volumes:
- /var/run/docker.sock:/var/run/docker.sock
restart: unless-stopped
```
Run:
```bash
docker compose -f deployment/docker-compose.yaml up -d
```
**Important Notes:**
- The bot needs access to the Docker socket to manage containers
- Ensure `/var/run/docker.sock` is mounted
- The bot container must be on the same Docker host as the Valheim server container
- This works with Portainer-managed stacks as well
4. **Using with Portainer**
You can deploy this stack through Portainer:
1. In Portainer, go to **Stacks** → **Add stack**
2. Name your stack (e.g., `valheim-discord-bot`)
3. Paste the docker-compose content from `deployment/docker-compose.yaml`
4. Set the environment variables in Portainer's environment variables section
5. Deploy the stack
The bot will manage your Valheim server container directly through the Docker API, no Portainer API configuration needed.