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:
Source code:
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.