Getting Started

This guide covers installing Kiselgram locally, configuring it, and running the development server. Production deployment is covered in Deployment.

Prerequisites

• Python 3.10+ (Python 3.11+ recommended for built-in tomllib)
• pip and venv
• Git (to clone the repository)

1. Clone & create a virtual environment

git clone <your-repo-url> kiselgram
cd kiselgram

python3 -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

2. Install dependencies

pip install -r requirements.txt

If you also want the video call server locally:

pip install -r video_server/requirements.txt

3. Setup

The setup command creates the required directories and a default config/kis.toml:

python manage.py setup

This creates:

• uploads/images, uploads/documents, uploads/media
• logs/
• status/
• config/kis.toml (default configuration)

4. Run

python manage.py start

The main app starts on http://localhost:5000 (default) and the video server on port 5001. On startup, the database tables are created automatically and standard bots are registered.

The first manage.py start opens a browser automatically. Pass --no-browser to disable that.

5. Verify

Open http://localhost:5000, register an account, and send your first message. A /health endpoint returns {"status": "ok"}.

manage.py reference

manage.py is the CLI entry point for running and maintaining the app.

python manage.py <command> [options]

start

Starts the main app and the video server as background services.

python manage.py start
python manage.py start --port 5500 --no-video --no-browser

stop / restart / status

python manage.py stop       # stop main + video
python manage.py restart    # restart all services
python manage.py status     # show running ports / PIDs

setup / clean / test

python manage.py setup      # create dirs + default config
python manage.py clean      # remove temp runner scripts
python manage.py test       # check basic dependencies

reset-db

Deletes all data. Destructive.

python manage.py reset-db -y

video subcommands

python manage.py video start [--port 5001]
python manage.py video stop

The full command list is available via python manage.py --help. The default config/kis.toml generated by setup pins version 2.0.0 in [app].version — update it if you want the header/metadata to reflect the current release.

Configuration

All runtime configuration lives in config/kis.toml (TOML). It is loaded by app/config.py on startup.

Minimal annotated example:

[app]
name = "Kiselgram"
version = "4.0.0"
debug = false                # NEVER true in production
host = "0.0.0.0"
port = 5000
secret_key = "change-me-in-production"

[database]
url = "sqlite:///kiselgram.db"      # dev
# url = "postgresql://user:pass@localhost/kiselgram"   # production

[server]
workers = 4

[video]
enabled = true
port = 5001
auto_start = true

[uploads]
folder = "uploads"
max_size = 16777216
allowed_images = [".jpg", ".jpeg", ".png", ".gif", ".bmp"]
allowed_documents = [".pdf", ".doc", ".docx", ".txt", ".md"]
allowed_videos = [".mp4", ".avi", ".mov", ".mkv"]

[features]
groups = true
channels = true
bots = true
video_streaming = true
file_sharing = true
reactions = true

[telegram]
bot_token = "YOUR_BOT_TOKEN_HERE"
webhook_url = ""

[mail]
server = "mail.kiselgram.ru"
port = 587
username = "auth@mail.kiselgram.ru"
password = ""
sender_name = "Kiselgram - Auth"
sender_email = "auth@mail.kiselgram.ru"

[google]
client_id = ""
client_secret = ""

[logging]
# per-service rotating file handlers

Environment variables (highest priority)

In production the following environment variables override TOML values:

If DATABASE_URL is set, the app switches to production mode automatically (debug forced off, secure cookies enforced).

Common development tasks

Run tests

.venv/bin/python -m pytest tests/ -v

See Testing for details.

Use the in-memory test DB

The test suite uses sqlite:///:memory: via tests/conftest.py.

Reset your local data

python manage.py reset-db -y

Start only the API with a custom port

python manage.py start --port 8099 --no-video --no-browser

Troubleshooting

ModuleNotFoundError: No module named 'flask' You are using a system Python, not the venv. Activate it first: source .venv/bin/activate.

Port already in use manage.py start checks and refuses to bind occupied ports. Find the offender with lsof -i :5000 and stop it, or pick another port.

Debug warning on startup ⚠️ DEBUG mode is ON — do not expose this server to the internet. Set debug = false in config/kis.toml or run with DATABASE_URL set.

Database errors / missing columns In dev, the schema is created with db.create_all(). For schema changes on existing DBs, prefer Alembic migrations (flask db migrate). See Deployment and Architecture.