Deploying StockUp: A Step-by-Step Guide

StockUp is a Telegram Web App designed for family inventory management. Its architecture consists of a Python FastAPI backend, a Go notifier worker, a Vanilla JS frontend, and relies on PostgreSQL and Redis. This guide explains how to deploy the application on your server.
You can also use our app directly, without self-hosting:

• How to use the app

Source code:

• GitHub

Prerequisites: Installing Docker

The StockUp project uses Docker to manage its services. This approach guarantees that the application runs consistently, regardless of your operating system. You must install Docker and Docker Compose before you begin.

Depending on your platform, follow the official documentation to install Docker:

• Linux: For most Linux distributions (like Ubuntu or Debian), you need to install Docker Engine. Official Guide for Linux
• Windows: If you are deploying on a Windows server or your personal computer, you must install Docker Desktop. Official Guide for Windows

Make sure Docker is running before moving to the next step.

Step 1: Environment Configuration

First, download the project code to your server.

In the root folder of the project, you will find a file named .env.example. You need to create a new file named .env and configure your specific variables.

Your .env file should look like this:

BOT_TOKEN=your_telegram_bot_token
WEBAPP_URL=https://your-domain.com/ 
DATABASE_URL=postgresql+asyncpg://stockup_user:stockup_password@db:5432/stockup_db
REDIS_URL=redis://redis:6379/0

• BOT_TOKEN: Get this from BotFather in Telegram.
• WEBAPP_URL: The HTTPS URL where your frontend will be available (e.g., using ngrok for local testing or a real domain).

Step 2: Running the Project

Because all services (Database, Redis, Backend, and Notifier) are defined in the docker-compose.yml file, starting the project is very simple.

Open your terminal, navigate to the project directory, and run the following command:

docker-compose up -d --build

• up: Starts the containers.
• --build: Forces Docker to build the images for the Backend and Notifier before starting.
• -d: Runs the containers in the background (detached mode).

Once the process finishes, the backend will be available at http://localhost:8000.

Step 3: Database Migrations

After starting the containers for the first time, you need to set up the database tables. Run this command to apply Alembic migrations:

docker-compose exec backend alembic upgrade head

Step 4: Monitoring and Maintenance

To check if everything works correctly, you can view the logs of your services. For example, to see the logs of the Go worker that sends Telegram messages, run:

docker-compose logs -f notifier

To stop the application, use:

docker-compose down

Conclusion

By using Docker, deploying StockUp requires only a few commands. Ensure your environment variables are correct and your Docker daemon is active, and your Telegram Web App will be ready to use.