Home

Deploying FastAPI and Flask Apps on Mikr.us VPS

0. GitHub Authentication (Personal Access Token)

GitHub has disabled password authentication for CLI operations. Before cloning your private repository on the VPS, you must generate a Personal Access Token (PAT).

How to generate a Token:

  1. Go to GitHub.com -> Settings -> Developer settings.
  2. Select Personal access tokens -> Tokens (classic).
  3. Click Generate new token (classic).
  4. Note: Give it a name (e.g., “VPS-Master”).
  5. Expiration: Set to your preference (e.g., 90 days or No expiration).
  6. Scopes: Check the repo box (allows cloning private repos).
  7. Click Generate token and COPY IT IMMEDIATELY. You won’t see it again.

How to use it on the VPS:

When you run git clone, Git will ask for your username and password:

1. Local Project Preparation

Ensure your project is container-ready before pushing to GitHub.

Step 1: Create a Dockerfile

Place this in your project root.

# Choose appropriate Python version
FROM python:3.13-slim

WORKDIR /app

# Install system dependencies if needed (e.g., for sqlite/pandas)
# RUN apt-get update && apt-get install -y gcc && rm -rf /var/lib/apt/lists/*

# Install Python requirements
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application code
COPY . .

# Expose internal port (FastAPI usually 8000, Flask 5000)
EXPOSE 8000

# Start command
CMD ["uvicorn", "src.server:app", "--host", "0.0.0.0", "--port", "8000"]

Step 2: Create a .gitignore

Ensure you don’t push secrets or large data files.

.env
__pycache__/
.venv/
data/*.db
data/*.json

2. Mikr.us Panel Setup

Mikr.us maps a public subdomain to a specific port on your VPS.

  1. Find your Assigned Ports:

    • Log in to panel.mikr.us.
    • Check “Udostepnione porty” (Shared Ports).
    • Pick a free port (e.g., 5002).

  2. Create a Subdomain:

    • Go to “Subdomeny” -> “Szybka subdomena”.
    • Name: your-app-name
    • Port: Enter your picked port (e.g., 5002).
    • This maps https://your-app.tojest.dev -> VPS_IP:5002.

3. VPS Integration (Master Compose Strategy)

It is best practice to manage all your apps from a single directory (e.g., vps-master) containing a single “Master” docker-compose.yml file. This allows you to manage multiple apps as a single stack or individual services.

Step 1: Organization

On your VPS, create a central management directory/ or go to that dir if already created:

mkdir -p ~/vps-master
cd ~/vps-master

Your folder structure should look like this:

vps-master/
├── docker-compose.yml (Master file)
├── app-1/
├── app-2/
└── your-new-repo/

Step 2: Clone the Project

Clone your GitHub repository inside the vps-master directory:

cd ~/vps-master
git clone https://github.com/your-username/your-repo.git

Step 3: Update the Master docker-compose.yml

Open the master file and add the new service. Use relative paths for the build, env_file, and volumes.

services:
  # Existing apps...

  # NEW APP: Your Project Name
  # URL: https://subdomain.tojest.dev
  app-container-name:
    build: ./your-repo-folder
    container_name: app-container-name
    restart: always
    env_file:
      - ./your-repo-folder/.env
    volumes:
      - ./your-repo-folder/data:/app/data  # Persist database/files
    ports:
      - "5002:8000"  # MIKRUS_PORT : INTERNAL_PORT

Step 3: Setup Environment

cd your-repo-folder
nano .env
# Add your API keys and secrets here

4. Launching the App

Step 1: Build and Run

From the directory containing the Master docker-compose.yml:

docker compose up -d --build app-container-name

Step 2: Initialize Data (If required)

If your app needs an initial data fetch or database setup:

docker exec app-container-name python src/setup_script.py

Step 3: Fix Permissions

If the container cannot write to the data/ folder:

sudo chown -R $USER:$USER ./your-repo-folder/data
chmod -R 775 ./your-repo-folder/data

5. Automation & Maintenance

Weekly Updates (Cron)

Use the VPS cron system to run tasks inside the container.

crontab -e

Add line:

0 3 * * 1 docker exec app-container-name python src/update.py >> /home/wga/your-repo-folder/cron.log 2>&1

Updating the Code

When you push new changes to GitHub:

cd your-repo-folder && git pull
cd ..
docker compose up -d --build app-container-name

Useful Commands

Tags: VpsMikrusFlaskFastapiPythonLinux