Getting Started
Relevant source files
The following files were used as context for generating this wiki page:Amina is a multipurpose, open-source Discord bot designed to protect communities, provide entertainment, and offer utility functions. This guide serves as the primary entry point for both server administrators looking to use the public bot and developers interested in self-hosting their own instance. It covers adding the bot to a server, initial configuration, and the steps required for a local or production deployment.
The bot is built with a "heart," giving it a distinct personality that is sharp, energetic, and blunt. It features a wide range of capabilities, from moderation and administration to high-quality music playback and an economy system. For a complete list of commands and features, refer to the Command Center Docs.
Sources: README.md, src/data/prompt.md:3-8
Adding Amina to Your Server
The quickest way to get started is by inviting the official, hosted version of Amina to your Discord server.
Upon joining a new server, Amina sends a welcome message outlining its core capabilities and prompting administrators to run the /admin command for configuration. A direct message is also sent to the user who invited the bot, reiterating the next steps.
Sources: README.md:30-34, src/data/respGuild.json:3-10, src/data/respGuild.json:11-17
Core Bot Commands
The primary interaction with the bot is through the /mina slash command, which provides access to essential information and links.
| Subcommand | Description |
|---|---|
invite | Get a link to add Amina to your server. |
stats | View system stats like memory, CPU, and server count. |
uptime | Check how long the bot has been running without a restart. |
donate | Access links to support development via Ko-fi or GitHub Sponsors. |
docs | Access the wiki and documentation. |
ping | Check the bot's response latency to Discord. |
changelog | See the latest updates and changes by fetching CHANGELOG.md from GitHub. |
Sources: src/commands/bot/bot.ts:16-46
The following diagram illustrates the flow for fetching the changelog.
This diagram shows the sequence of events when a user requests the bot's changelog.
Sources: src/commands/bot/bot.ts:153-176
Initial Server Configuration
After adding Amina to a server, administrators should configure it to suit their community's needs. The /settings status command provides a comprehensive overview of all configurable modules.
The following diagram shows the process of retrieving and displaying server settings.
This flowchart illustrates how the bot fetches, formats, and displays server settings in a paginated embed.
Sources: src/commands/admin/settings/status.ts
Configurable Features
The table below lists the key features that can be configured and the primary commands used to manage them.
| Feature | Description | Configuration Command |
|---|---|---|
| Prefix | The command prefix (legacy). | /settings prefix |
| Log Channel | Channel for moderation logs. | /logs channel |
| Max Warns | Action to take when a user reaches max warnings. | /maxwarn |
| Welcome/Farewell | Greeting and departure messages for members. | /welcome, /farewell |
| Auto Role | Automatically assign roles to new members. | /autorole |
| Counter Channels | Display server stats (e.g., member count) in channel names. | /counter |
| Ticket System | User support ticket system with categories. | /ticket |
| Automod | Automated moderation for spam, links, invites, etc. | /automod |
| Stats Channels | Dedicated channels for server statistics. | /stats |
| Staff Roles | Roles designated as server staff. | /settings staffadd/staffremove |
| Giveaways | Manage server giveaways. | /giveaway |
| Reaction Roles | Allow users to get roles by reacting to a message. | /reactionrole |
Sources: src/commands/admin/settings/status.ts:13-200
Self-Hosting Guide
For developers who wish to run their own instance of Amina, the project is containerized using Docker and can be deployed locally or on a server.
Sources: README.md:78-82, scripts/local.sh
Prerequisites
- Git: For cloning the repository.
- Docker: For running the application and its services (Lavalink, Uptime Kuma).
- Docker Permissions: The user running the script must be in the
dockergroup to execute Docker commands withoutsudo.
Sources: scripts/local.sh:65-111
Environment Configuration
Amina is configured via environment variables. A .env file must be created in the deployment directory. The following table details the available variables, derived from app.json.
| Variable | Description | Required | Default Value |
|---|---|---|---|
BOT_TOKEN | Discord Bot Token from the Developer Portal. | Yes | |
MONGO_CONNECTION | MongoDB connection string. | Yes | |
WEBHOOK_SECRET | Secure string for dashboard webhook authentication. | No | |
LOGS_WEBHOOK | Discord webhook URL for bot logs. | No | |
LAVALINK_HOST_1 | Primary Lavalink node host. | No | lavalink |
LAVALINK_PORT_1 | Primary Lavalink node port. | No | 2333 |
LAVALINK_PASSWORD_1 | Primary Lavalink node password. | No | incorrect |
LAVALINK_ID_1 | Primary Lavalink node identifier. | No | Lavalink |
LAVALINK_SECURE_1 | Use secure connection for primary Lavalink node. | No | false |
SPOTIFY_CLIENT_ID | Spotify API client ID for music playback. | No | |
SPOTIFY_CLIENT_SECRET | Spotify API client secret. | No | |
GEMINI_KEY | Google Gemini API Key for AI features. | No | |
UPSTASH_VECTOR | Upstash Vector Database token for AI memory. | No | |
WEATHERSTACK_KEY | API key for the /weather command. | No | |
STRANGE_API_KEY | API key for image manipulation commands. | No | |
GH_TOKEN | GitHub token for the /changelog command. | No | |
HONEYBADGER_API_KEY | Honeybadger API key for error tracking. | No |
Sources: app.json:4-88
Deployment Process
The scripts/local.sh script automates the setup of the deployment directory. It clones the repository, copies necessary configuration files, and prepares the environment for launch.
The following diagram outlines the deployment flow:
This flowchart shows the steps executed by the local.sh deployment script.
Sources: scripts/local.sh:118-241
Project Scripts
The package.json file contains several scripts for development and management, which are executed using bun.
| Script | Description |
|---|---|
dev | Run the bot in development mode with hot-reloading. |
build | Run type checking and format checking. |
start | Start the bot. |
f | Format all files with Prettier. |
f:check | Check for formatting issues with Prettier. |
check | Run TypeScript compiler and ESLint. |
eslint | Run ESLint. |
eslint:fix | Run ESLint and automatically fix issues. |
prepare | Install Husky git hooks. |
Sources: package.json:9-18