ByteBeacon

Open-source API and uptime monitoring for developers.

Quick start · API overview · Configuration · Notifications · Deployment

ByteBeacon is a FastAPI-based monitoring service that checks public HTTP and HTTPS endpoints on a schedule, records availability and latency, tracks incidents, and can deliver notifications through Telegram.

Project status: ByteBeacon is under active development. APIs and configuration may change between releases.

Highlights

• Email-verified registration and cookie-based access and refresh-token authentication
• Profile editing with verification before an email change takes effect
• Monitor creation, listing, updating, activation, and deletion
• Configurable check intervals and request timeouts
• Check history with status codes, latency, and error details
• Automatic incident creation and recovery tracking
• Telegram account linking, monitor management, status views, and incident notifications
• Email incident notifications through an SMTP server
• Delivery status tracking and duplicate notification prevention
• OpenAPI documentation generated by FastAPI
• Async PostgreSQL access through SQLAlchemy and asyncpg
• Alembic migrations for database schema management

Architecture

                         ┌──────────────────────┐
                         │     FastAPI API      │
                         │  REST API · Auth     │
                         └──────────┬───────────┘
                                    │
                         ┌──────────▼───────────┐
                         │   Monitor Scheduler  │
                         │  Async Monitoring    │
                         └──────────┬───────────┘
                                    │
                         ┌──────────▼───────────┐
                         │      PostgreSQL      │
                         │   Persistent Data    │
                         └──────────┬───────────┘
                                    │
                                    ▼
                    ┌──────────────────────────────┐
                    │     Public HTTP / HTTPS      │
                    │       Monitor Targets        │
                    └──────────────────────────────┘

The scheduler reconciles active monitors and runs checks at each monitor's configured interval. A check is considered successful for HTTP status codes from 200 through 399. Monitor targets must resolve exclusively to public IP addresses; private and loopback destinations are rejected.

Requirements

• Python 3.10 or newer
• PostgreSQL 13 or newer
• A virtual environment is recommended
• Telegram credentials are required only for Telegram integration
• SMTP credentials are required for registration and email notifications

Quick start

1. Clone and enter the repository

git clone https://github.com/Atila-Pasha/ByteBeacon.git
cd ByteBeacon

2. Create a virtual environment

python -m venv .venv
source .venv/bin/activate

On Windows, activate the environment with:

.venv\Scripts\Activate.ps1

3. Install dependencies

python -m pip install --upgrade pip
pip install -r requirements.txt

4. Configure the environment

Create a local environment file from the example:

cp .env.example .env

Set valid PostgreSQL connection strings and replace SECRET_KEY with a long, random value. Configure SMTP to deliver registration codes. Configure the Telegram variables when bot support is needed. Never commit .env or any other file containing credentials.

5. Create the database schema

alembic upgrade head

6. Start the API

uvicorn app.main:app --reload

The service is available at http://127.0.0.1:8000.

Interactive API documentation is available at:

• Swagger UI: http://127.0.0.1:8000/docs
• ReDoc: http://127.0.0.1:8000/redoc
• Health check: http://127.0.0.1:8000/health

API overview

All application routes are prefixed with /v1. Protected routes authenticate using the HTTP-only cookies created by the login and refresh endpoints, or an Authorization: Bearer <token> header.

Area	Method	Endpoint	Authentication
Health	GET	/health	Public
Auth	POST	/v1/auth/register	Public
Auth	POST	/v1/auth/verify-email, /v1/auth/resend-verification	Public
Auth	POST	/v1/auth/login	Public
Auth	POST	/v1/auth/refresh	Refresh cookie
Auth	POST	/v1/auth/logout	Optional refresh cookie
Users	GET	/v1/users/me	Required
Users	PATCH	/v1/users/me	Required
Users	POST	/v1/users/me/verify-email	Required
Monitors	GET, POST	/v1/monitors	Required
Monitor	GET, PATCH, DELETE	/v1/monitors/{monitor_id}	Required
Checks	GET	/v1/monitors/{monitor_id}/checks	Required
Incidents	GET	/v1/monitors/{monitor_id}/incidents	Required
Telegram	POST	/v1/users/me/telegram/token	Required
Telegram	GET, DELETE	/v1/users/me/telegram	Required
Telegram	POST	/v1/telegram/connect	Public token exchange

Monitor intervals are expressed in minutes and must be greater than zero. Bare domains such as google.com are normalized to https://google.com/. Monitor targets must resolve only to public IP addresses.

Configuration

Copy .env.example to .env and provide values for the required settings.

Variable	Required	Default	Purpose
APP_NAME	No	ByteBeacon	Application name
APP_VERSION	No	0.1.0	API version displayed by FastAPI
DEBUG	No	false	Enables development behavior, including non-secure cookies
DATABASE_URL	Yes	None	Async SQLAlchemy PostgreSQL URL
DATABASE_SYNC_URL	Yes	None	Synchronous PostgreSQL URL for Alembic
SECRET_KEY	Yes	None	JWT signing key
ALGORITHM	No	HS256	JWT signing algorithm
ACCESS_TOKEN_EXPIRE_MINUTES	No	15	Access-token lifetime
REFRESH_TOKEN_EXPIRE_DAYS	No	7	Refresh-token lifetime
EMAIL_VERIFY_EXPIRE_MINUTES	No	15	Email code lifetime
CHECK_TIMEOUT	No	10.0	HTTP check timeout in seconds
SCHEDULER_ENABLED	No	true	Starts the monitor scheduler in this process
TELEGRAM_BOT_TOKEN	No	Empty	Telegram bot token
TELEGRAM_BOT_USERNAME	No	Empty	Telegram bot username for linking
TELEGRAM_LINK_EXPIRE_MINUTES	No	10	Telegram linking-token lifetime
TELEGRAM_API_TIMEOUT	No	10.0	Telegram API timeout in seconds
TELEGRAM_PROXY_URL	No	Empty	Optional SOCKS proxy for Telegram traffic
SMTP_HOST	No	Empty	SMTP server hostname
SMTP_PORT	No	587	SMTP server port
SMTP_USER	No	Empty	SMTP authentication username
SMTP_PASSWORD	No	Empty	SMTP authentication password or app password
SMTP_FROM_EMAIL	No	Empty	Sender email address
SMTP_FROM_NAME	No	ByteBeacon	Sender display name
SMTP_USE_TLS	No	true	Use STARTTLS for SMTP connections
SMTP_USE_SSL	No	false	Use implicit SSL, commonly on port 465

Telegram integration

To link an account, an authenticated client requests a short-lived Telegram connection token from POST /v1/users/me/telegram/token. The response includes a Telegram start link. After the bot receives the link, the connection is completed through POST /v1/telegram/connect.

Provide TELEGRAM_BOT_TOKEN and TELEGRAM_BOT_USERNAME in .env to enable the integration. TELEGRAM_PROXY_URL can be set when the Telegram API is only reachable through a proxy.

The private-chat bot offers /menu, /monitors, /status, /incidents, /new, /cancel, and /disconnect. Monitor buttons show recent checks and allow editing, pausing, resuming, and deletion with confirmation. Every action is limited to monitors owned by the linked ByteBeacon account.

Notifications

ByteBeacon sends notifications when a monitor goes down and when it recovers. Notifications are delivered independently to every channel configured for the user:

• Telegram messages are sent through the Telegram Bot API after the user's account is linked.
• Email messages are sent through SMTP using the user's registered email address.

The notification service records the channel, provider, event type, delivery status, error details, and timestamp. Each incident and event type is sent only once per channel, preventing duplicate alerts when a scheduler cycle is repeated.

Email setup

Set all SMTP variables in .env to enable email delivery. For a provider that uses STARTTLS, such as Gmail SMTP, use port 587 with SMTP_USE_TLS=true and SMTP_USE_SSL=false. For implicit SSL, commonly port 465, use SMTP_USE_SSL=true and disable STARTTLS.

Registration requires SMTP delivery. New accounts cannot sign in until the six-digit code sent to their address is verified. Codes expire after 15 minutes, can be resent after one minute, and stop working after five wrong attempts. Changing an account email sends a fresh code to the new address; the previous address remains active until verification. Existing accounts are marked verified by the migration. Use an app password when the email provider requires one; never commit SMTP credentials to the repository.

Development

Run the test suite with:

pytest

Run a focused test module with:

pytest tests/monitoring/test_checker.py -q

Create a new migration after changing models:

alembic revision --autogenerate -m "describe the schema change"
alembic upgrade head

Deployment

Run the scheduler in exactly one process or deployment replica. Set SCHEDULER_ENABLED=false on API-only replicas, and enable it only for the dedicated monitoring worker. Otherwise every replica checks every monitor and creates duplicate check records and notifications.

Run database migrations as a release step before starting application processes. Keep DEBUG=false in production, use a unique high-entropy SECRET_KEY, and store all secrets in the deployment platform's secret manager.

Because the scheduler performs outbound requests, deploy it with network egress access while retaining the application's public-target validation.

Project layout

app/
├── api/v1/        HTTP routes and request handling
├── bot/           Telegram bot lifecycle integration
├── core/          Settings, logging, and security
├── db/            SQLAlchemy engine and base configuration
├── models/        Database models
├── monitoring/    Scheduler and endpoint checker
├── notifications/ Notification adapters
├── schemas/       Pydantic request and response models
└── services/      Application and domain services
alembic/           Database migration history
tests/             Unit and integration tests

License

See LICENSE for the project license.