Deployment on Yandex Cloud

The cloud version of Notifly runs entirely on Yandex Cloud serverless services: there are no always-on VMs, billing is only for actual traffic and storage.

This document describes how the deployed stack is organized and how to reproduce it in your own folder.

Architecture

┌──────────────────────────────────────────────────────────────────────────┐
│                                Клиент                                    │
│  (браузер · Android · desktop · MCP-агент · cron · веб-сайт · SMTP)      │
└──────┬──────────────┬──────────────┬───────────────┬────────────────────┘
       │ HTTPS REST   │ WSS          │ POST /script  │ SMTP
       ▼              ▼              ▼               ▼
┌──────────────────────────────────────────────────────────────────────────┐
│                  Yandex Cloud API Gateway (notifly-ws-gateway)           │
│  ─ /api/*         → notifly-api      (REST)                              │
│  ─ /ws            → notifly-ws-handler (WebSocket)                       │
│  ─ /script/*      → notifly-api      (публичные web-script триггеры)     │
└──────┬─────────────────────┬──────────────────────────┬─────────────────┘
       │                     │                          │
       ▼                     ▼                          ▼
┌──────────────┐   ┌──────────────────┐    ┌────────────────────────────┐
│ notifly-api  │   │ notifly-ws-      │    │ notifly-email              │
│ (golang121)  │   │ handler          │    │ (Mail Trigger → Email Inbox)│
└─────┬────────┘   │ (golang123)      │    └──────────┬─────────────────┘
      │            └──────┬───────────┘               │
      │                   │                           │
      ▼                   ▼                           ▼
┌──────────────────────────────────────────────────────────────────────────┐
│                         YDB Serverless (notifly-db)                      │
│ users · applications · clients · messages · webhooks · email_inboxes     │
│ web_scripts · heartbeats · monitors · mcp_tokens · channel_shares        │
└──────────────────────────────────────────────────────────────────────────┘
                                  ▲
       ┌──────────────────────────┴──────────────────────────┐
       │ Object Storage notifly-ws-connections                │
       │ connections/<id>.json — состояние WebSocket-сессий   │
       └──────────────────────────────────────────────────────┘

       Timer triggers (cron `* * * * ? *`):
       • notifly-heartbeat   — проверяет просроченные heartbeat-ы
       • notifly-monitor     — выполняет активные проверки HTTP/TCP/TLS/...

Component	Resource	Type
notifly-api	Cloud Function	REST + Web Script triggers
notifly-ws-handler	Cloud Function	WebSocket handler
notifly-email	Cloud Function	receiving emails via Mail Trigger
notifly-heartbeat	Cloud Function	timer check of heartbeats
notifly-monitor	Cloud Function	timer check of active monitors
notifly-ws-gateway	API Gateway	single entry point
notifly-db	YDB Serverless	all business logic
notifly-ws-connections	Object Storage	state of WebSocket connections

What’s missing in the cloud

When migrating from the self-hosted version the following were deliberately excluded:

• Go plugins (.so) — the YC Functions runtime does not support them. See Introduction to plugins for alternatives.
• OIDC — authorization is only local (BasicAuth + Bearer tokens).
• Embed UI — the frontend is deployed separately to the app.notifly.ru bucket.
• Image upload — a stub (uploading images to Object Storage — on the roadmap).
• Fractional sort keys for messages — simplified to a string field.

Preparation

You will need:

• a Yandex Cloud account with a folder;
• the yc CLI (installation);
• a service account with roles serverless.functions.admin, ydb.admin, storage.editor, api-gateway.admin;
• static access keys for the service account (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY) — for S3 from Cloud Function;
• an IAM token (short-lived, 12 hours) — for the deployment itself.

All secrets are kept in .env at the repository root and are loaded via set -a; source .env; set +a before running the deploy scripts.

Deployment steps

1. Create YDB and tables

yc ydb database create notifly-db --serverless
# .env: YDB_DSN=grpcs://ydb.serverless.yandexcloud.net:2135/?database=...

cd server_ya
go run ./cmd/initdb     # creates schema + admin/admin

The initdb script is idempotent: rerunning it won’t break existing tables or recreate the admin.

2. Create S3-bucket for WebSocket

yc storage bucket create --name notifly-ws-connections --max-size 1073741824

3. Deploy REST + WebSocket + API Gateway

cd server_ya
bash deploy/deploy.sh

The script:

1. Builds a zip for notifly-api and uploads it as a Cloud Function;
2. Builds a zip for notifly-ws-handler and uploads it as a Cloud Function;
3. Applies a unified OpenAPI specification to the API Gateway (REST /{proxy+} + WebSocket /ws).

If you redeploy ws-handler/deploy.sh separately — it will overwrite the API Gateway with a WS-only spec; to restore REST, rerun server_ya/deploy/deploy.sh.

4. Deploy timer functions (heartbeat, monitor)

cd server_ya
bash deploy/deploy_heartbeat.sh
bash deploy/deploy_monitor.sh

Each script creates a Cloud Function and attaches a timer-trigger with the schedule * * * * ? * (once per minute). Inside the function a SELECT WHERE next_check_at <= now() is executed using the corresponding YDB index.

5. Deploy email function (optional)

cd server_ya
bash deploy/deploy_email.sh

After deployment, in the console bind the notifly-email function to the desired mailbox (<local>+<alias>@<domain>). User mailboxes are managed via Email Inbox — aliases are stored in YDB, and Mail Trigger routes emails based on the subaddress part.

6. Deploy frontend

cd admin_ya
npm ci
npm run build
bash deploy.sh   # synchronizes dist/ to the app.notifly.ru bucket

See also admin deployment instructions — this step is largely automated.

Smoke test

After deployment run:

bash server_ya/deploy/smoke_test.sh
python3 server_ya/deploy/ws_test.py

Check:

• GET /health → {"health":"green","database":"green"}
• POST /auth/local/login (Basic admin/admin)
• POST /application + POST /message ×N
• GET /message, GET /application/{id}/message
• wss://.../ws?token=<C...> — handshake 101, ping → pong, status with connection_id and source_ip.

Operations

Action	Where to check
Function logs	yc logging read --group-id <log-group> --format json
Function metrics	Yandex Cloud Console → Cloud Functions → metrics
YDB table state	YDB UI or yc ydb yql ...
Active WS connections	aws s3 ls s3://notifly-ws-connections/connections/

`yc logging read` hangs in WSL

In WSL the standard yc logging read can hang — use --format json | tee or read via the Yandex Cloud Console.

Costs

The stack is optimized for the FREE-tier:

• YDB Serverless — Request Units, no always-on storage; indexes on next_check_at provide O(1) checks in the heartbeat/monitor timers.
• Cloud Functions — billed by millisec-execution. Functions wake up only on activity (POST /message, ping, cron).
• Object Storage — a few bytes per WebSocket connection (connections/<id>.json ~200 bytes).
• API Gateway — billed per request.

With zero activity Notifly consumes nothing except the fee for reserved space in YDB (~10 ₽/month on the free-tier).