Self.Nokiy.Net

A FastAPI application with Rust-powered markdown processing, featuring:

• FastAPI web framework with async support
• SQLModel/SQLAlchemy ORM with PostgreSQL
• Rust extensions via PyO3 for high-performance markdown parsing
• Docker containerization for easy deployment

Quick Start

Development with Docker Compose

1. Clone and setup:

   git clone <repository>
   cd self.nokiy.net
   cp .env.example .env  # Edit as needed
   

2. Start all services:

   # Production mode
   docker-compose up -d
   
   # Development mode (with hot reload)
   docker-compose --profile dev up -d
   

3. Access the application:

   • Production: http://localhost:8000
   • Development: http://localhost:8001
   • Health check: http://localhost:8000/health
   • API docs: http://localhost:8000/docs

Local Development (without Docker)

1. Install dependencies:

   # Install UV package manager if not installed
   curl -LsSf https://astral.sh/uv/install.sh | sh
   
   # Install Python dependencies
   uv sync
   
   # Build Rust extension
   cd nokiy/doc
   uv run maturin develop
   cd ../..
   

2. Setup database:

   # Start only PostgreSQL
   docker-compose up -d postgres
   

3. Run the application:

   uv run -- uvicorn src.main:app --reload
   

Docker Services

Production Services

• app: Main FastAPI application (port 8000)
• postgres: PostgreSQL database (port 5432)

Development Services

• app-dev: Development server with hot reload (port 8001)

Optional Services

• valkey: Redis-compatible cache (commented out by default)

Docker Commands

# Build and start all services
docker-compose up -d

# Start with development profile
docker-compose --profile dev up -d

# View logs
docker-compose logs -f app

# Stop all services
docker-compose down

# Rebuild application image
docker-compose build app

# Clean up (removes volumes)
docker-compose down -v

Project Structure

├── src/
│   ├── main.py              # FastAPI application entrypoint
│   ├── config.py            # App config
│   ├── route/               # API route handlers
│   └── model/               # Data models
├── nokiy/
│   ├── doc/                 # Markdown processing (Rust) + Python bindings
│   │   ├── src/             # Rust sources (lib.rs, doc.rs, ast.rs)
│   │   └── python/nokiy/doc # Python package wrapping the Rust module
│   ├── store/               # Storage/data logic (Rust)
│   ├── server/              # Server utilities (Rust)
│   └── cli/                 # CLI (Rust)
└── docker-compose.yaml

Development

Adding Dependencies

# Python dependencies
uv add package-name

# Rust dependencies (in nokiy/doc/)
cd nokiy/doc
cargo add crate-name

Building Rust Extension

cd nokiy/doc
uv run maturin develop  # Development build
uv run maturin build    # Production wheel

• Maturin is configured to enable the Rust crate feature py_ext automatically (see nokiy/doc/pyproject.toml).

Rust Tests and Coverage

• Run all Rust tests for the workspace (requires DB up):

just test-rust

• Generate Rust coverage (HTML + LCOV) for all nokiy crates:

# Recommended (requires: cargo install cargo-llvm-cov)
just coverage

# If cargo-llvm-cov is not installed, the recipe falls back to manual instrumentation
# and produces a merged .profdata file under target/coverage.

Focused Rust Dev for nokiy/doc

These tasks do not require a running Python interpreter for tests (the crate is feature-gated):

# Run nokiy/doc tests only (isolated target dir to avoid locks)
just doc-test

# Format and lint the doc crate
just doc-fmt
just doc-clippy

# Build/install the Python extension in the current env
just doc-develop

# Build distributable wheels
just doc-build-wheel

Notes on Rust Python Gating (py_ext)

• The nokiy/doc crate uses a feature flag py_ext to compile Python bindings.
• Rust unit tests run without linking against Python by default.
• The Python wheel built via Maturin enables py_ext automatically.
• MIME detection prefers Python Magika when running inside Python; otherwise falls back to infer crate and file extension mapping.

API Endpoints

• GET /health - Health check endpoint
• GET /posts - List all posts
• POST /posts - Create a new post
• PUT /posts/{id} - Update existing post
• DELETE /posts/{id} - Delete post

Configuration

Environment Variables

Key environment variables (see .env.example):

• DATABASE_URL: PostgreSQL connection string
• RUST_LOG: Logging level for Rust components
• PYTHONPATH: Python module search path
• FASTAPI_ENV: Application environment (development/production)

Database

The application uses PostgreSQL with SQLModel for ORM operations. Database tables are automatically created on startup.

Deployment

Production Deployment

1. Configure environment:

   cp .env.example .env
   # Edit .env with production values
   

2. Deploy with Docker Compose:

   docker-compose up -d
   

3. Monitor logs:

   docker-compose logs -f
   

Health Monitoring

The application includes health check endpoints and Docker health checks:

• Application health: GET /health
• Database health: Built into PostgreSQL service
• Container health: Configured in docker-compose.yaml

Troubleshooting

Common Issues

1. Port conflicts: Change ports in docker-compose.yaml if 8000/5432 are in use
2. Database connection: Ensure PostgreSQL is running and accessible
3. Rust build errors: Check that Rust toolchain is properly installed
4. Import errors: Verify that the nokiy.doc package is properly built and installed

Debug Commands

# Check service status
docker-compose ps

# View application logs
docker-compose logs app

# Access database
docker-compose exec postgres psql -U nokiy -d nokiy

# Access application container
docker-compose exec app bash