Skip to content
Nani PixNani Pix guide

Run your own Nani Pix

Nani Pix runs entirely in Docker: her own container plus a MariaDB database, wired together by the repository’s docker-compose.yml. This page walks through setting up your own copy from nothing.

What you need

Section titled “What you need”
  • A machine with Docker and the Docker Compose plugin (docker compose version should work).
  • A Telegram account.

Nothing else is installed on the host. The Docker image already contains the ffmpeg build Nani Pix uses to render her end-of-round reveal videos.

1. Create a Telegram bot

Section titled “1. Create a Telegram bot”
  1. Open a chat with @BotFather and send /newbot.
  2. Follow the prompts to pick a name and a username ending in bot.
  3. BotFather replies with a token such as 123456789:AAExampleTokenTextHere. This is your BOT_TOKEN. Keep it secret: anyone with it can control your bot.

2. Set up your group and topic

Section titled “2. Set up your group and topic”
  1. Create a Telegram group, or use an existing one, and turn on Topics (Group settings → Topics). Nani Pix posts into one specific topic, not the main chat.
  2. Add your bot to the group and make it an admin with at least the Pin messages permission. Nani Pix pins the current round’s picture; without the permission she simply skips pinning.
  3. Create or pick the topic the game will be played in.

3. Find your group and topic ids

Section titled “3. Find your group and topic ids”

Before starting Nani Pix (so nothing else is reading your bot’s updates), send any command in the game topic, for example /start. It’s fine that nothing answers yet. Then open this address in a browser, with your real token:

https://api.telegram.org/bot<BOT_TOKEN>/getUpdates

In the JSON response, find that message and read:

  • result[].message.chat.id: your GROUP_CHAT_ID, a negative number such as -1001234567890.
  • result[].message.message_thread_id: your GAME_TOPIC_ID.

It has to be a command: by default, bots in groups only receive commands, replies to themselves and mentions.

4. Configure

Section titled “4. Configure”

Copy the example settings file and fill it in (see Configuration for every setting):

Terminal window
cp .env.example .env

5. Run it

Section titled “5. Run it”

Build from source:

Terminal window
docker compose build
docker compose up -d
docker compose logs -f bot

Or use a ready-made image: in docker-compose.yml, replace the bot service’s build: . with image: ghcr.io/sm-steel/nani-pix-bot:X.Y.Z (the available versions are on the Releases page), and run the same commands without docker compose build.

Nani Pix updates her database by herself every time she starts, after MariaDB is ready, so there’s no separate migration step. Once she’s up, the logs show her polling Telegram. Send /version in your topic to check that she answers.

The database keeps its data in a Docker volume named mariadb_data. Nani Pix reaches it over the Compose network as mariadb:3306, not localhost.

Next steps

Section titled “Next steps”