Update "Installation"
k.eaven committed
1 parent
369560ac8b
commit
625d9e60bd
1 file changed
+411
+411
@@ -0,0 +1,411 @@
|
|||||||
|
# Installation
|
||||||
|
|
||||||
|
## Prerequisites
|
||||||
|
|
||||||
|
Before installing Pterodisbot, ensure you have:
|
||||||
|
|
||||||
|
- **Python 3.8 or higher** (for traditional installation)
|
||||||
|
- **Docker** (for containerized deployment)
|
||||||
|
- **Kubernetes cluster** (for K8s deployment)
|
||||||
|
- **Discord bot token** (from Discord Developer Portal)
|
||||||
|
- **Discord server (guild) ID**
|
||||||
|
- **Pterodactyl/Pelican Panel** with API access
|
||||||
|
- **Pterodactyl Client API key** (starts with `ptlc_` or `pacc_`)
|
||||||
|
- **Pterodactyl Application API key** (starts with `ptla_` or `papp_`)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Discord Bot Setup
|
||||||
|
|
||||||
|
Before installing the bot software, you need to create a Discord application and bot account.
|
||||||
|
|
||||||
|
### 1. Create Discord Application
|
||||||
|
|
||||||
|
1. Navigate to the [Discord Developer Portal](https://discord.com/developers/applications)
|
||||||
|
2. Click the **"New Application"** button in the top-right corner
|
||||||
|
3. Enter a name for your application (e.g., "Pterodactyl Bot")
|
||||||
|
4. Accept the Terms of Service and click **"Create"**
|
||||||
|
|
||||||
|
### 2. Configure Bot Settings
|
||||||
|
|
||||||
|
1. In the left sidebar, click on **"Bot"**
|
||||||
|
2. Click **"Add Bot"** and confirm by clicking **"Yes, do it!"**
|
||||||
|
3. Under the bot's username, you'll see a **Token** section:
|
||||||
|
- Click **"Reset Token"** and then **"Copy"** to get your bot token
|
||||||
|
- ⚠️ **Keep this token secret!** Never share it publicly or commit it to version control
|
||||||
|
4. Scroll down to **"Privileged Gateway Intents"** and enable:
|
||||||
|
- ✅ **Message Content Intent** (required for the bot to read message content)
|
||||||
|
5. Click **"Save Changes"** at the bottom
|
||||||
|
|
||||||
|
### 3. Set Bot Permissions
|
||||||
|
|
||||||
|
1. In the left sidebar, click on **"OAuth2"** → **"URL Generator"**
|
||||||
|
2. Under **"Scopes"**, select:
|
||||||
|
- ✅ `bot`
|
||||||
|
- ✅ `applications.commands`
|
||||||
|
3. Under **"Bot Permissions"**, select:
|
||||||
|
- ✅ **View Channels** (allows bot to see channels)
|
||||||
|
- ✅ **Send Messages** (allows bot to post embeds)
|
||||||
|
- ✅ **Embed Links** (required for rich embeds)
|
||||||
|
- ✅ **Attach Files** (required for metrics graphs)
|
||||||
|
- ✅ **Read Message History** (allows bot to edit existing messages)
|
||||||
|
- ✅ **Use Slash Commands** (required for `/server_status` commands)
|
||||||
|
|
||||||
|
### 4. Invite Bot to Your Server
|
||||||
|
|
||||||
|
1. Copy the **Generated URL** at the bottom of the OAuth2 URL Generator page
|
||||||
|
2. Paste this URL into your browser and press Enter
|
||||||
|
3. Select the Discord server where you want to add the bot
|
||||||
|
4. Click **"Authorize"** and complete the CAPTCHA if prompted
|
||||||
|
5. The bot should now appear in your server (offline until you start the application)
|
||||||
|
|
||||||
|
### 5. Get Your Guild ID
|
||||||
|
|
||||||
|
1. In Discord, enable **Developer Mode**:
|
||||||
|
- Click the ⚙️ gear icon (User Settings)
|
||||||
|
- Navigate to **"Advanced"** under "App Settings"
|
||||||
|
- Toggle on **"Developer Mode"**
|
||||||
|
2. Right-click on your server icon in the left sidebar
|
||||||
|
3. Click **"Copy Server ID"** at the bottom of the menu
|
||||||
|
4. Save this ID - you'll need it for the bot configuration
|
||||||
|
|
||||||
|
### 6. Create Server Role
|
||||||
|
|
||||||
|
1. In your Discord server, click the server name at the top to open the dropdown menu
|
||||||
|
2. Select **"Server Settings"** → **"Roles"**
|
||||||
|
3. Click **"Create Role"**
|
||||||
|
4. Name the role exactly: `Game Server User`
|
||||||
|
5. The role doesn't need any special permissions - it's only used for bot access control
|
||||||
|
6. Click **"Save Changes"**
|
||||||
|
7. Assign this role to any users who should be able to control game servers
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Traditional Installation
|
||||||
|
|
||||||
|
### 1. Clone the Repository
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://git.serendipity.systems/k.eaven/pterodisbot.git
|
||||||
|
cd pterodactyl-discord-bot
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Install Required Dependencies
|
||||||
|
|
||||||
|
```bash
|
||||||
|
pip install -r requirements.txt
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Create and Configure Your `config.ini` File
|
||||||
|
|
||||||
|
See the [Configuration](/Configuration) section for details.
|
||||||
|
|
||||||
|
### 4. Run the Bot
|
||||||
|
|
||||||
|
```bash
|
||||||
|
python main.py
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Docker Installation
|
||||||
|
|
||||||
|
### 1. Clone the Repository
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://git.serendipity.systems/k.eaven/pterodisbot.git
|
||||||
|
cd pterodactyl-discord-bot
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Build the Docker Image
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker build -t pterodisbot .
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Create a Directory for Configuration
|
||||||
|
|
||||||
|
```bash
|
||||||
|
mkdir -p bot-config
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Create a `config.ini` File
|
||||||
|
|
||||||
|
Create a `config.ini` file in the `bot-config` directory with your settings (see [Configuration](/Configuration)).
|
||||||
|
|
||||||
|
### 5. Run the Container
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker run -d \
|
||||||
|
--name pterodisbot \
|
||||||
|
-v $(pwd)/bot-config:/app \
|
||||||
|
pterodisbot
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. Docker Compose (Recommended)
|
||||||
|
|
||||||
|
Create a `docker-compose.yml` file:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
services:
|
||||||
|
pterodisbot:
|
||||||
|
build: .
|
||||||
|
environment:
|
||||||
|
# Remove brackets and spaces in environment variables
|
||||||
|
# Ideally, use .env file to assign values to these instead
|
||||||
|
- DISCORD_TOKEN={Your Discord bot token from Developer Portal}
|
||||||
|
- ALLOWED_GUILD_ID={Your Discord server ID from step 5 above}
|
||||||
|
- PANEL_URL={Your Pterodactyl panel URL with https://}
|
||||||
|
- CLIENT_API_KEY={Pterodactyl client API key starting with ptlc_}
|
||||||
|
- APPLICATION_API_KEY={Pterodactyl application API key starting with ptla_}
|
||||||
|
volumes:
|
||||||
|
- bot_logs:/app/logs
|
||||||
|
- bot_embed:/app/embed
|
||||||
|
restart: unless-stopped
|
||||||
|
|
||||||
|
volumes:
|
||||||
|
bot_logs:
|
||||||
|
bot_embed:
|
||||||
|
```
|
||||||
|
|
||||||
|
Then run:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker-compose up -d
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Kubernetes Installation
|
||||||
|
|
||||||
|
### 1. Clone the Repository
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone https://git.serendipity.systems/k.eaven/pterodisbot.git
|
||||||
|
cd pterodactyl-discord-bot
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. Build and Push the Docker Image
|
||||||
|
|
||||||
|
```bash
|
||||||
|
docker build -t your-registry/pterodisbot:latest .
|
||||||
|
docker push your-registry/pterodisbot:latest
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. Create a Kubernetes Namespace (Optional but Recommended)
|
||||||
|
|
||||||
|
```bash
|
||||||
|
kubectl create namespace pterodisbot
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. Create a Kubernetes Secret with Your Configuration
|
||||||
|
|
||||||
|
```bash
|
||||||
|
kubectl create secret generic pterodisbot-config \
|
||||||
|
--from-literal=DISCORD_TOKEN='your-discord-bot-token' \
|
||||||
|
--from-literal=ALLOWED_GUILD_ID='your-discord-guild-id' \
|
||||||
|
--from-literal=PANEL_URL='https://your.pterodactyl.panel' \
|
||||||
|
--from-literal=CLIENT_API_KEY='ptlc_your-client-api-key' \
|
||||||
|
--from-literal=APPLICATION_API_KEY='ptla_your-application-api-key' \
|
||||||
|
-n pterodisbot
|
||||||
|
```
|
||||||
|
|
||||||
|
### 5. Create a PersistentVolumeClaim for Logs and Embed Data
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# pvc.yaml
|
||||||
|
apiVersion: v1
|
||||||
|
kind: PersistentVolumeClaim
|
||||||
|
metadata:
|
||||||
|
name: pterodisbot-data
|
||||||
|
namespace: pterodisbot
|
||||||
|
spec:
|
||||||
|
accessModes:
|
||||||
|
- ReadWriteOnce
|
||||||
|
resources:
|
||||||
|
requests:
|
||||||
|
storage: 1Gi
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
kubectl apply -f pvc.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
### 6. Create the Deployment
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# deployment.yaml
|
||||||
|
apiVersion: apps/v1
|
||||||
|
kind: Deployment
|
||||||
|
metadata:
|
||||||
|
name: pterodisbot
|
||||||
|
namespace: pterodisbot
|
||||||
|
labels:
|
||||||
|
app: pterodisbot
|
||||||
|
spec:
|
||||||
|
replicas: 1
|
||||||
|
selector:
|
||||||
|
matchLabels:
|
||||||
|
app: pterodisbot
|
||||||
|
template:
|
||||||
|
metadata:
|
||||||
|
labels:
|
||||||
|
app: pterodisbot
|
||||||
|
spec:
|
||||||
|
containers:
|
||||||
|
- name: pterodisbot
|
||||||
|
image: your-registry/pterodisbot:latest
|
||||||
|
imagePullPolicy: Always
|
||||||
|
envFrom:
|
||||||
|
- secretRef:
|
||||||
|
name: pterodisbot-config
|
||||||
|
volumeMounts:
|
||||||
|
- name: pterodisbot-data
|
||||||
|
mountPath: /app/logs
|
||||||
|
subPath: logs
|
||||||
|
- name: pterodisbot-data
|
||||||
|
mountPath: /app/embed
|
||||||
|
subPath: embed
|
||||||
|
resources:
|
||||||
|
requests:
|
||||||
|
memory: "256Mi"
|
||||||
|
cpu: "100m"
|
||||||
|
limits:
|
||||||
|
memory: "512Mi"
|
||||||
|
cpu: "500m"
|
||||||
|
livenessProbe:
|
||||||
|
exec:
|
||||||
|
command: ["python", "-c", "import sys; sys.exit(0)"]
|
||||||
|
initialDelaySeconds: 30
|
||||||
|
periodSeconds: 30
|
||||||
|
readinessProbe:
|
||||||
|
exec:
|
||||||
|
command: ["python", "-c", "import sys; sys.exit(0)"]
|
||||||
|
initialDelaySeconds: 10
|
||||||
|
periodSeconds: 10
|
||||||
|
volumes:
|
||||||
|
- name: pterodisbot-data
|
||||||
|
persistentVolumeClaim:
|
||||||
|
claimName: pterodisbot-data
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
kubectl apply -f deployment.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
### 7. (Optional) Create a Service for Metrics/Health Checks
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# service.yaml
|
||||||
|
apiVersion: v1
|
||||||
|
kind: Service
|
||||||
|
metadata:
|
||||||
|
name: pterodisbot
|
||||||
|
namespace: pterodisbot
|
||||||
|
labels:
|
||||||
|
app: pterodisbot
|
||||||
|
spec:
|
||||||
|
selector:
|
||||||
|
app: pterodisbot
|
||||||
|
ports:
|
||||||
|
- name: http
|
||||||
|
port: 8080
|
||||||
|
targetPort: 8080
|
||||||
|
type: ClusterIP
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
kubectl apply -f service.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8. (Optional) Create a HorizontalPodAutoscaler
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# hpa.yaml
|
||||||
|
apiVersion: autoscaling/v2
|
||||||
|
kind: HorizontalPodAutoscaler
|
||||||
|
metadata:
|
||||||
|
name: pterodisbot
|
||||||
|
namespace: pterodisbot
|
||||||
|
spec:
|
||||||
|
scaleTargetRef:
|
||||||
|
apiVersion: apps/v1
|
||||||
|
kind: Deployment
|
||||||
|
name: pterodisbot
|
||||||
|
minReplicas: 1
|
||||||
|
maxReplicas: 3
|
||||||
|
metrics:
|
||||||
|
- type: Resource
|
||||||
|
resource:
|
||||||
|
name: cpu
|
||||||
|
target:
|
||||||
|
type: Utilization
|
||||||
|
averageUtilization: 70
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
kubectl apply -f hpa.yaml
|
||||||
|
```
|
||||||
|
|
||||||
|
### 9. Verify the Deployment
|
||||||
|
|
||||||
|
```bash
|
||||||
|
kubectl get pods -n pterodisbot
|
||||||
|
kubectl logs -n pterodisbot -l app=pterodisbot -f
|
||||||
|
```
|
||||||
|
|
||||||
|
### 10. For Production: Use Kustomize
|
||||||
|
|
||||||
|
Create a `kustomization.yaml`:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# kustomization.yaml
|
||||||
|
apiVersion: kustomize.config.k8s.io/v1beta1
|
||||||
|
kind: Kustomization
|
||||||
|
namespace: pterodisbot
|
||||||
|
resources:
|
||||||
|
- pvc.yaml
|
||||||
|
- deployment.yaml
|
||||||
|
- service.yaml
|
||||||
|
- hpa.yaml
|
||||||
|
images:
|
||||||
|
- name: pterodisbot
|
||||||
|
newTag: latest
|
||||||
|
commonLabels:
|
||||||
|
app: pterodisbot
|
||||||
|
```
|
||||||
|
|
||||||
|
```bash
|
||||||
|
kubectl apply -k .
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Verification
|
||||||
|
|
||||||
|
After installation, verify the bot is working:
|
||||||
|
|
||||||
|
1. Check the bot appears online in your Discord server
|
||||||
|
2. Use `/server_status` command to create your first status embed
|
||||||
|
3. Verify buttons work (Start/Stop/Restart/Show Address)
|
||||||
|
4. Check logs for any errors:
|
||||||
|
```bash
|
||||||
|
# Traditional
|
||||||
|
tail -f logs/pterodisbot.log
|
||||||
|
|
||||||
|
# Docker
|
||||||
|
docker logs -f pterodisbot
|
||||||
|
|
||||||
|
# Kubernetes
|
||||||
|
kubectl logs -n pterodisbot -l app=pterodisbot -f
|
||||||
|
```
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Related Pages
|
||||||
|
|
||||||
|
- [Architecture](/Architecture) - System design
|
||||||
|
- [Configuration](/Configuration) - Config options
|
||||||
|
- [Usage](/Usage) - Commands and workflows
|
||||||
|
- [Features](/Features) - Feature details
|
||||||
|
- [Contributing](/Contributing) - Development guidelines
|
||||||
Reference in new issue
Block a user