Skip to content
Surkyl Docs

Surkyl Server

Surkyl Server

Section titled “Surkyl Server”

Surkyl Server is the main backend service for the Surkyl Platform, providing authentication, role-based access control (RBAC), and core API functionality.

Overview

Section titled “Overview”

Built with Rust, Axum, and SQLx, Surkyl Server provides a high-performance, type-safe backend with PostgreSQL database integration.

Technology Stack:

  • Language: Rust
  • Web Framework: Axum 0.8
  • Database: PostgreSQL with SQLx
  • Authentication: JWT tokens
  • Access Control: Guardian RBAC system

Key Features

Section titled “Key Features”

Authentication & Authorization

Section titled “Authentication & Authorization”
  • JWT-based authentication
  • Refresh token rotation
  • Session management
  • Role-based access control (RBAC)

Guardian Access Control System

Section titled “Guardian Access Control System”

Comprehensive access control system with:

  • Fine-grained permissions
  • Resource-level access control
  • Hierarchical roles
  • Dynamic permission evaluation

Learn more about Guardian →

Database Management

Section titled “Database Management”
  • Type-safe database queries with SQLx
  • Automated migrations
  • Connection pooling
  • Transaction support

API Features

Section titled “API Features”
  • RESTful APIs
  • OpenAPI/Swagger documentation
  • Browsable API Interface - Interactive testing in browser
  • CORS configuration
  • Request validation

Learn more about Browsable API →

Quick Start

Section titled “Quick Start”

Prerequisites

Section titled “Prerequisites”
  • Rust (latest stable)
  • PostgreSQL 14+
  • SQLx CLI: cargo install sqlx-cli

Setup Database

Section titled “Setup Database”
Terminal window
# Create database
createdb surkyl_server


# Run migrations
cd apps/surkyl-server
sqlx database setup

Configuration

Section titled “Configuration”

Create configs/surkyl-server.config.yml:

server:
    host: '0.0.0.0'
    port: 8080
    show_version: true


database:
    url: 'postgresql://postgres:postgres@localhost:5432/surkyl_server'
    max_connections: 10


security:
    jwt_secret: 'your-secret-key-change-in-production'
    access_token_ttl:
        hours: 1
    refresh_token_ttl:
        days: 14

Run Server

Section titled “Run Server”
Terminal window
# Development
cargo run --bin surkyl-server


# Or with Nx
nx serve surkyl-server


# Production build
nx build surkyl-server

Architecture

Section titled “Architecture”

Stack Overview

Section titled “Stack Overview”

Learn about the Rust + Axum + SQLx stack:

Stack Overview →

RBAC System

Section titled “RBAC System”

Understand the role-based access control system:

RBAC & Permissions →

Guardian System

Section titled “Guardian System”

Deep dive into the Guardian access control architecture:

Guardian Architecture →

API Documentation

Section titled “API Documentation”

The server provides OpenAPI documentation at:

  • JSON: http://localhost:8080/openapi.json
  • YAML: http://localhost:8080/openapi.yml

Browsable API Interface

Section titled “Browsable API Interface”

When you access any API endpoint from a web browser, you’ll see an interactive testing interface instead of raw JSON. This allows you to:

  • Explore all available endpoints
  • Send test requests with custom parameters and headers
  • View formatted responses with syntax highlighting
  • Copy requests as cURL commands

Full Browsable API Documentation →

Development

Section titled “Development”

Running Tests

Section titled “Running Tests”
Terminal window
cargo test

Database Migrations

Section titled “Database Migrations”
Terminal window
# Create new migration
sqlx migrate add <migration_name>


# Run migrations
sqlx migrate run


# Revert last migration
sqlx migrate revert

Environment Variables

Section titled “Environment Variables”

Override configuration with environment variables:

Terminal window
SURKYL_SERVER__SERVER__PORT=3000
SURKYL_SERVER__DATABASE__URL="postgresql://..."
SURKYL_SERVER__SECURITY__JWT_SECRET="..."

Docker Deployment

Section titled “Docker Deployment”
Terminal window
cd apps/surkyl-server
docker-compose up

Next Steps

Section titled “Next Steps”