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:
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/tmpand/var/tmp(64 MiB each, kept in memory and gone at restart): see Limits and isolation. - Choose the Python version with a
.python-versionfile at the root containing just the version, for example3.12. Without it the bot uses its Python setting (3.9 to 3.15; an AI assistant sets it withset_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)")
/datais not executable: a program written there cannot be started./tmpand/var/tmpare 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/dataonce 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.