formies/README.md

Formies Backend

A production-ready Rust backend for the Formies application.

Features

• RESTful API endpoints
• SQLite database with connection pooling
• JWT-based authentication
• Rate limiting
• Structured logging
• Error tracking with Sentry
• Health check endpoint
• CORS support
• Configuration management
• Metrics endpoint

Prerequisites

• Rust 1.70 or later
• SQLite 3
• Make (optional, for using Makefile commands)

Configuration

The application can be configured using environment variables or a configuration file. The following environment variables are supported:

Required Environment Variables

• DATABASE_URL: SQLite database URL (default: form_data.db)
• BIND_ADDRESS: Server bind address (default: 127.0.0.1:8080)
• INITIAL_ADMIN_USERNAME: Initial admin username
• INITIAL_ADMIN_PASSWORD: Initial admin password

Optional Environment Variables

• ALLOWED_ORIGIN: CORS allowed origin
• RUST_LOG: Log level (default: info)
• SENTRY_DSN: Sentry DSN for error tracking
• JWT_SECRET: JWT secret key
• JWT_EXPIRATION: JWT expiration time in seconds
• CAPTCHA_ENABLED: Enable CAPTCHA verification for public form submissions (true or false, default: false)
• CAPTCHA_SECRET_KEY: The secret key provided by your CAPTCHA service (e.g., hCaptcha, reCAPTCHA)
• CAPTCHA_VERIFICATION_URL: The verification endpoint URL for your CAPTCHA service (e.g., https://hcaptcha.com/siteverify)

Development

1. Clone the repository
2. Install dependencies:

   cargo build
   

3. Set up environment variables:

   cp .env.example .env
   # Edit .env with your configuration
   

4. Run the development server:

   cargo run
   

Production Deployment

Docker

1. Build the Docker image:

   docker build -t formies-backend .
   

2. Run the container:

   docker run -d \
     --name formies-backend \
     -p 8080:8080 \
     -v $(pwd)/data:/app/data \
     -e DATABASE_URL=/app/data/form_data.db \
     -e BIND_ADDRESS=0.0.0.0:8080 \
     -e INITIAL_ADMIN_USERNAME=admin \
     -e INITIAL_ADMIN_PASSWORD=your-secure-password \
     -e ALLOWED_ORIGIN=https://your-frontend-domain.com \
     -e SENTRY_DSN=your-sentry-dsn \
     formies-backend
   

Systemd Service

1. Create a systemd service file at /etc/systemd/system/formies-backend.service:

   [Unit]
   Description=Formies Backend Service
   After=network.target
   
   [Service]
   Type=simple
   User=formies
   WorkingDirectory=/opt/formies-backend
   ExecStart=/opt/formies-backend/formies-be
   Restart=always
   Environment=DATABASE_URL=/opt/formies-backend/data/form_data.db
   Environment=BIND_ADDRESS=0.0.0.0:8080
   Environment=INITIAL_ADMIN_USERNAME=admin
   Environment=INITIAL_ADMIN_PASSWORD=your-secure-password
   Environment=ALLOWED_ORIGIN=https://your-frontend-domain.com
   Environment=SENTRY_DSN=your-sentry-dsn
   
   [Install]
   WantedBy=multi-user.target
   

2. Enable and start the service:

   sudo systemctl enable formies-backend
   sudo systemctl start formies-backend
   

Monitoring

Health Check

The application exposes a health check endpoint at /api/health:

curl http://localhost:8080/api/health

Metrics

Metrics are available at /metrics when enabled in the configuration.

Logging

Logs are written to the configured log file and can be viewed using:

tail -f logs/app.log

Security

• All API endpoints are rate-limited
• CORS is configured to only allow specified origins
• JWT tokens are used for authentication
• Passwords are hashed using bcrypt
• SQLite database is protected with proper file permissions

Form Submission Security

The public form submission endpoint (/api/forms/{form_id}/submissions) includes several security measures:

• Global Rate Limiting: The overall number of requests to the API is limited.
• Per-Form, Per-IP Rate Limiting: Limits the number of submissions one IP address can make to a specific form within a time window (e.g., 5 submissions per minute). Configurable in code.
• CAPTCHA Verification: If enabled via environment variables (CAPTCHA_ENABLED=true), requires a valid CAPTCHA token (e.g., from hCaptcha, reCAPTCHA, Turnstile) to be sent in the captcha_token field of the submission payload. The backend verifies this token with the configured provider.
• Payload Size Limit: The maximum size of the submission payload is limited (e.g., 1MB) to prevent DoS attacks. Configurable in code.
• Input Validation: Submission data is validated against the specific form's field definitions (type, required, length, pattern, etc.).
• Notification Throttling: Limits the rate at which notifications (Email, Ntfy) are sent per form to prevent spamming channels (e.g., max 1 per minute). Configurable in code.

License

MIT