Skip to content

Preparing your code

BotBarn builds a container image from your code on every deploy. It looks at the root of your repository or archive.

How BotBarn decides what to build

At the root What BotBarn does
Containerfile or Dockerfile Builds it as it is. Any language. The image's CMD starts the bot.
main.py, bot.py or app.py (no Containerfile) Generates a Python image (the version you choose, 3.14 by default), installs requirements.txt if present, and runs the first of these files.
None of these The build fails with No Containerfile, Dockerfile, main.py, bot.py, or app.py found.

A Containerfile wins over a Dockerfile, and both win over the Python files.

Python without a Containerfile

The simplest layout:

my-bot/
├── main.py
└── requirements.txt

BotBarn generates this image:

FROM docker.io/library/python:3.14-slim
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1 PIP_DISABLE_PIP_VERSION_CHECK=1
RUN useradd --create-home --uid 10001 --user-group bot
WORKDIR /app
COPY --chown=bot:bot . /app
RUN pip install --no-cache-dir -r requirements.txt
USER bot
CMD ["python", "-u", "main.py"]
  • Pin your dependencies in requirements.txt (python-telegram-bot==22.8), so a deploy next month builds the same bot.
  • The bot runs as an unprivileged user (uid 10001) on a read-only root filesystem. It can write in /data (persistent, sized by the plan) and in /tmp and /var/tmp (64 MiB each, kept in memory and gone at restart): see Limits and isolation.
  • Choose the Python version with a .python-version file at the root containing just the version, for example 3.12. Without it the bot uses its Python setting (3.9 to 3.15; an AI assistant sets it with set_python_version), Python 3.14 by default.
  • System packages (apt-get) need your own Containerfile.

Keep data in /data

Everything that must outlive a restart or a deploy goes in /data: the bot's own persistent folder, sized by the plan. Use SQLite in WAL mode (PRAGMA journal_mode=WAL) or plain files:

import sqlite3

db = sqlite3.connect("/data/bot.sqlite")
db.execute("PRAGMA journal_mode=WAL")
db.execute("CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)")
  • /data is not executable: a program written there cannot be started. /tmp and /var/tmp are still memory.
  • A write over the plan's limit fails with "disk quota exceeded"; the bot keeps running. The Overview shows use and limit.
  • Files keep their numeric owner (uid). With the built-in build the bot is always uid 10001. With your own Containerfile run as one fixed user (USER 10001); if you change it, reset /data once or the new user cannot write the old files.
  • The folder is deleted with the bot and 7 days after the plan ends. Download it from the bot's Overview (Data card) or through your AI assistant at any time; Reset empties it.

Your own Containerfile

Use one for any language, any base image and any version, or for system packages. Example for Node.js:

FROM docker.io/library/node:22-alpine
ENV NODE_ENV=production
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev --no-audit --no-fund && rm -rf /root/.npm
COPY bot.js ./
USER node
CMD ["node", "bot.js"]

Good practice:

  • Use full image names (docker.io/library/node:22-alpine) and pin versions.
  • Run as a non-root user (USER).
  • Copy the dependency files first and the code after, so builds are faster.
  • Print logs to standard output. Do not write them to files.
  • The build has 15 minutes and can download packages from the internet. Your variables are not available during the build, only when the bot runs.

Archives

  • Formats: .zip, .tar.gz, .tgz. Up to 20 MB.
  • An archive with a single top-level folder is unwrapped, so a GitHub "Download ZIP" works as it is.
  • Archives with absolute paths, .., links or special files are refused.
  • Leave out node_modules, virtual environments and .git: BotBarn installs dependencies itself.

Git repositories

  • HTTPS URLs only (https://github.com/you/my-bot.git), with a branch name.
  • For a private repository, add an access token with read access to that repository only. For GitHub, a fine-grained token with Contents: Read-only. Do not put the token in the URL.
  • BotBarn fetches the latest commit of the branch on every deploy. Pushing does not redeploy: press Deploy when you want the new code live.

Checklist

  • [ ] The bot reads the token from TELEGRAM_BOT_TOKEN.
  • [ ] Settings come from environment variables, not from files in the repository.
  • [ ] The entry point is at the root: a Containerfile, or main.py / bot.py / app.py.
  • [ ] Dependencies are pinned.
  • [ ] The bot uses the BotBarn webhook variables, or long polling with a 30-second timeout: Polling or webhook.