Quick Start

Install, configure, and run PyPing locally.

PyPing runs as a single FastAPI process. You need Python 3.11+ and a PostgreSQL database.

1. Clone and install dependencies

git clone https://github.com/yourname/pyping.git
cd pyping
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

2. Create the environment file

Copy .env.example to .env and fill in your values:

DATABASE_URL=postgresql+asyncpg://user:pass@localhost/pyping
SECRET_KEY=your-random-secret-key
APP_NAME=PyPing
APP_BASE_URL=http://localhost:8000

# Optional — SMTP alerts
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=you@gmail.com
SMTP_PASSWORD=app-password
SMTP_FROM=you@gmail.com
ALERT_EMAIL=recipient@email.com

# Optional — Telegram alerts
TELEGRAM_BOT_TOKEN=123456:ABC...
TELEGRAM_CHAT_ID=-100123456789

# Optional — Google SSO
GOOGLE_CLIENT_ID=xxx.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=GOCSPX-...

3. Apply database schema

alembic upgrade head

On first run the app seeds default settings automatically.

4. Start the server

uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

Open http://localhost:8000 in your browser and register the first admin account.

Production deploy — Use PM2 or systemd to keep the process alive. See the deploy guide in docs/deploy.md for Nginx reverse-proxy and PostgreSQL setup.

Environment Variables Reference

VariableRequiredDescription
DATABASE_URLRequiredAsync PostgreSQL connection string (postgresql+asyncpg://…)
SECRET_KEYRequiredRandom string for JWT signing. Generate with openssl rand -hex 32
APP_NAMEOptionalDisplay name shown in the UI. Default: PyPing
APP_BASE_URLOptionalOrigin used for CORS. Default: http://localhost:8000
SMTP_*OptionalSMTP credentials for email alerts
TELEGRAM_BOT_TOKENOptionalBot token from @BotFather
TELEGRAM_CHAT_IDOptionalGroup or channel chat ID for alert delivery
GOOGLE_CLIENT_IDOptionalEnables Google OAuth login button
LOG_LEVELOptionalINFO / DEBUG / WARNING. Default: INFO