Site Card

Containerized micro-service web business-card platform

Overview

SiteCard is a micro-service, container-ready web platform for creating interactive personal/business web cards with Telegram WebApp integration.

Services & Tools

• App Service: Ruby web application. Handles primary site UI, authentication, asset delivery, and gRPC notifications.
• Notification Bot: Python, async Telegram bot (aiogram/telethon, gRPC). Delivers contact forms, manages user authorization, and pushes notifications for site events.
• Database: PostgreSQL service with migration/init scripts. Stores user data, contacts, portfolio, skills, and experience records.
• Keygen Utility: Containerized Go + OpenSSL tool to generate PQC admin keys (setup/maintenance).

Deployment

1. Clone the repository:

   git clone https://github.com/Mournweiss/site-card.git
   
   cd site-card

2. Place SSL certificates:

   All your SSL certificates (in .crt format: domain, root, intermediate, etc.) and private key (.key) provided by your certificate authority or domain registrar must be put inside the certs/ directory in the project root. NGINX will automatically detect and process all .crt files for use as the certificate chain, and only a single .key file (the main private key) must be provided.

   Note: NGINX ONLY accepts certificates in .crt format (not in .der, .p7b or .p7c). Do NOT place .csr files (certificate signing requests) inside certs/. They are only used to request certificates from a Certificate Authority and are not needed by NGINX or the running site.

3. Prepare and run orchestration script:

   chmod +x build.sh
   
   ./build.sh

   build.sh arguments:

   --docker, -d              Use docker-compose backend orchestration
   --podman, -p              Use podman-compose as orchestrator
   --telegram-token, -t ARG  Inject a Telegram bot token into .env (required)
   --domain, -dmn ARG        Inject a public domain name into the .env file (required)
   --no-keygen, -n           Skip admin key generation
   --foreground, -f          Run containers in foreground
   

   Note: build.sh automatically selects an available orchestration engine if no specific option is given. To force a specific orchestrator, use the --podman/-p or --docker/-d argument as needed.

4. Access app:

   • Main site (HTTP): http://localhost:9292
   • Telegram Bot: as specified by NOTIFICATION_BOT_TOKEN.

Deployment Modes

SiteCard supports two deployment modes based on SSL certificate and DOMAIN configuration:

• DEV_MODE (local HTTP): If the project does not find valid SSL certificates and key file in the certs/ directory, it automatically runs in development mode, exposing the main site via local HTTP on the port specified by NGINX_HTTP_PORT (default: 9292). This mode is intended for local testing and development only.

• PROD_MODE (global HTTPS): If valid SSL certificate chain files and a private key are present in the certs/ directory, and the DOMAIN variable is properly configured, the platform runs securely in production mode, serving the site globally over HTTPS on the port specified by NGINX_HTTPS_PORT (default: 9393).

Note: Mode selection is performed automatically at project startup, no manual intervention is required beyond managing the certificate/key files and configuration.

User Data Volume

This project uses the userdata/ directory (Docker volume) to support runtime file updates without rebuilding containers, enabling dynamic management of:

• avatar.<ext> - user avatar (must be exactly named avatar with one of the supported extensions (png, jpg, jpeg); extension must match the image_ext field in the database table avatars)

• CV.pdf - user CV/resume in PDF format

• favicon.ico - site favicon for browser tab and branding

Primary Environment Variables

• PRIVATE_KEY_PATH — Absolute path to the admin's private key (default: /certs/private_key.der).
• PUBLIC_KEY_PATH — Absolute path to the admin's public key (default: /certs/public_key.pem).
• WEBAPP_SECRET_PATH — Absolute path to the private key file used for JWT/WebApp token signing/validation (default: /certs/webapp_secret.der).
• KEYS_ENCRYPTION — Algorithm for admin keypair generation; must match platform requirements (default: ML-KEM-512).
• DOMAIN — Public domain (for links and Telegram WebApp integration).
• NOTIFICATION_BOT_TOKEN — Telegram Bot token from @BotFather.
• DEBUG — Enable debug output (true/false).
• PROJECT_NAME — Project identifier, used as prefix for names of all services and orchestration objects (containers, networks, volumes) in the stack (default: site-card).
• NGINX_HTTPS_PORT — Port for NGINX HTTPS using in PROD_MODE (default: 9393).
• NGINX_HTTP_PORT — Port for NGINX HTTP using in DEV_MODE (default: 9292).
• RACKUP_PORT — Internal Ruby backend port (default: 9191).
• NOTIFICATION_BOT_PORT — gRPC port for notification bot microservice (default: 50051).