From 625d9e60bda56c164aa2de4a69d7f00ad1b3d720 Mon Sep 17 00:00:00 2001 From: Eaven Kimura Date: Mon, 26 Oct 2026 12:10:22 +0000 Subject: [PATCH] Update "Installation" --- Installation.md | 411 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 411 insertions(+) diff --git a/Installation.md b/Installation.md index e69de29..ddd50de 100644 --- a/Installation.md +++ b/Installation.md @@ -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 \ No newline at end of file