Txlog Server Documentation

The Txlog Server is the core component of the platform, responsible for managing authentication, persisting transaction logs, and exposing the REST API used by agents and user interfaces. It orchestrates communication between services, ensuring data integrity and enforcing configured retention and security policies.

TL;DR

-- Create the database
CREATE DATABASE txlog;

# Run the server
docker run -d --name txlog-server \
  -e PGSQL_HOST=db.example.com \
  -e PGSQL_USER=txlog \
  -e PGSQL_PASSWORD=txlog \
  -e PGSQL_DB=txlog \
  -p 8080:8080 \
  ghcr.io/txlog/server:main

1. Tutorials

Learning-oriented lessons for beginners.

• Getting Started: Set up the server locally with Docker.
• Your First API Request: Learn how to interact with the API.

2. How-to Guides

Task-oriented guides for specific goals.

Authentication & Security

• Configure OIDC Authentication: Connect with Google, Keycloak, etc.
• Configure LDAP Authentication: Connect with Active Directory or OpenLDAP.
• Configure Anonymous LDAP: For servers without service accounts.
• Discover LDAP Filters: How to find the right query filters for your directory.
• Manage API Keys: Create and revoke keys for agents.

Operations

• Configure Data Retention: Manage database cleanup policies.
• Run Database Migrations: Apply schema changes safely.
• Deploy to Kubernetes: Production deployment manifest.

Development

• Add a New Endpoint: Workflow for contributors.
• Run Tests: Execute the test suite.

3. Reference

Information-oriented technical descriptions.

System

• API Reference: High-level API overview.
• Database Schema: Tables, columns, and relationships.
• Environment Variables: Complete configuration reference.

LDAP Specifics

• LDAP Cheatsheet: Quick reference for variables and common setups.
• LDAP Error Codes: Troubleshooting common error codes (32, 49, 50).
• LDAP Filters Reference: Common filter patterns for AD, OpenLDAP, etc.

4. Explanation

Understanding-oriented background knowledge.

Architecture

• System Architecture: High-level design, stack, and distributed scheduler.
• Data Model: Entities and relationships explanation.

Deep Dives

• LDAP Authentication Deep Dive: Comprehensive guide to how LDAP auth works.
• LDAP Implementation Details: Internal code structure of the LDAP module.
• LDAP Service Accounts FAQ: Best practices for bind accounts.
• Testing Strategy: Overview of the test suite and coverage goals.

5. API Documentation

When the server is running, interactive API documentation is available at: http://localhost:8080/swagger/index.html

• Source: docs/docs.go (Generated from code comments)
• Update: Run make doc to regenerate.