Quick Start Self Hosting

Quick start (self-hosting)

This guide provides instructions for deploying a self-hosted instance of the Amina bot. The primary deployment method uses Docker and Docker Compose to orchestrate the necessary services, including the bot itself, a Lavalink server for music playback, and an Uptime Kuma instance for monitoring.

Self-hosting is intended for users with technical knowledge of Docker, server management, and environment configuration. For most users, the official hosted version is recommended as it is always up-to-date and requires no setup.

Relevant source files

• scripts/local.sh
• README.md
• app.json
• package.json
• src/config/config.ts

Sources: README.md:82-86, scripts/local.sh

Prerequisites

Before starting the deployment, ensure the following tools are installed on your host system. The deployment script (scripts/local.sh) can automatically install these on Debian/Ubuntu systems.

• Git: For cloning the repository.
• Docker: For running the containerized services.
• Docker Compose: For managing the multi-container application.

Sources: scripts/local.sh:80-97

Deployment methods

The repository provides a shell script to automate the setup process.

Deployment script (scripts/local.sh)

This script is for deploying Amina on the machine where the script is executed (e.g., your local machine or a VPS). It clones the repository, sets up the required configuration files in a specified deployment path, and provides instructions to start the services.

Sources: scripts/local.sh:5-15

Deployment process

The deployment script follows a standardized, multi-step process to ensure a consistent and correct setup.

This diagram illustrates the automated workflow executed by the deployment script.

flowchart TD
    Start(Start) --> Validate[Validate Prerequisites: git, docker]
    Validate --> Clone[Clone Amina Repository Temporarily]
    Clone --> Check[Check for Required Files: .env, docker-compose.prod.yml, etc.]
    Check --> Prepare[Prepare Deployment Directory]
    Prepare --> Copy[Copy & Rename Config Files]
    Copy --> Perms[Set .env Permissions to 600]
    Perms --> Cleanup[Cleanup Temporary Cloned Repo]
    Cleanup --> Display[Display Next Steps to User]
    Display --> End(End)

Loading

Sources: scripts/local.sh

Final directory structure

After a successful deployment, the specified deployment directory (default: ~/amina) will have the following structure:

~/amina/
  ├── docker-compose.yml
  ├── .env
  ├── lavalink-entrypoint.sh
  └── lavalink/
      └── application.yml

This structure separates the core configuration from the application logic, which is pulled via Docker images.

Sources: scripts/local.sh:189-197

Configuration

Proper configuration is critical for the bot to function. The deployment scripts set up the necessary files, but you must populate them with your own secrets and settings.

Environment variables (.env)

The .env file contains secrets and essential configuration for the bot. It is created from .env.example if it doesn't already exist in the deployment directory. The following variables are required.

Variable	Description	Required
BOT_TOKEN	Your Discord bot token from the developer portal.	Yes
MONGO_CONNECTION	Connection URL for your MongoDB Atlas or self-hosted database.	Yes
LOGS_WEBHOOK	A Discord webhook URL for receiving error logs.	Yes
WEATHERSTACK_KEY	API key from weatherstack.com for the weather command.	No
STRANGE_API_KEY	API key for strangeapi.xyz.	No
SPOTIFY_CLIENT_ID	Spotify client ID for music commands.	No
SPOTIFY_CLIENT_SECRET	Spotify client secret for music commands.	No
OPENAI	API key for OpenAI or compatible service for AI commands.	No
GH_TOKEN	GitHub token for GitHub-related commands.	No

Sources: app.json:4-40, scripts/local.sh:162-168

Lavalink configuration

Lavalink is the music server that powers Amina's audio playback features.

• lavalink/application.yml: This file configures the Lavalink server. It is crucial to set a secure password under server.password. This password must match the LAVALINK_NODES configuration in your .env file.
• lavalink-entrypoint.sh: A helper script that ensures the correct permissions are set for the Lavalink server inside its container.

Sources: scripts/local.sh:30-31, scripts/local.sh:172-177, src/config/config.ts:80-88

Docker compose

The docker-compose.yml file is copied from docker-compose.prod.yml in the source repository. It defines and orchestrates the three main services:

1. Amina: The main bot application.
2. Lavalink: The music server.
3. Uptime Kuma: A monitoring dashboard.

The following diagram shows the relationship between these containerized services.

graph TD
    subgraph "User's VPS"
        subgraph "Docker Environment"
            A[Amina Bot Container]
            B[Lavalink Container]
            C[Uptime Kuma Container]
        end
        D[External MongoDB]
    end
    E[Developer]

    E -- Manages --> "Docker Environment"
    A -- Connects to --> B
    A -- Connects to --> D
    E -- Accesses --> C

Loading

Sources: scripts/vps.sh:10-16, scripts/vps.sh:152-154, app.json:9-13

Post-deployment

Once the deployment script finishes, it will output a list of next steps. You must complete these to get your bot online.

1. Review Configurations:

   • cat ~/amina/docker-compose.yml
   • cat ~/amina/lavalink/application.yml (Verify server.password)
   • cat ~/amina/.env (Fill in all required variables)

2. Start Services: Navigate to the deployment directory and start the containers in detached mode.

   cd ~/amina
   docker compose up -d

3. Check Status: Verify that all containers are running.

   docker compose ps

4. View Logs: Tail the logs for all services to check for errors.

   docker compose logs -f

5. Access Uptime Kuma: The monitoring dashboard will be available at http://<your-vps-ip>:3001.

Sources: scripts/local.sh:200-225, scripts/vps.sh:278-303