Skip to content

Your First Spartan Server

This tutorial will guide you through creating and running your own Spartan protocol server.

Level: Beginner Time: 15 minutes

Prerequisites

Step 1: Create a document directory

First, create a directory to hold your server's content:

mkdir my-capsule
cd my-capsule

Step 2: Create your first page

Create an index.gmi file with some Gemtext content:

# Welcome to My Capsule

This is my first Spartan capsule, served with Teyaotlani!

## About

Teyaotlani is a modern Spartan protocol implementation.

=> about.gmi Learn more about this capsule
=> spartan://example.com/ Visit example.com

Step 3: Add more content

Create an about.gmi file:

# About This Capsule

This capsule is powered by Teyaotlani, a Python implementation of the Spartan protocol.

## What is Spartan?

Spartan is a simple, text-focused protocol similar to Gemini, but without TLS complexity.

=> / Back to home

Step 4: Run the server (CLI)

The quickest way to start your server is using the CLI:

teyaotlani serve . --port 3000

You should see output like:

Starting Spartan server on localhost:3000
Serving files from: /path/to/my-capsule
Press Ctrl+C to stop

Step 5: Test your server

In another terminal, test your server:

teyaotlani get spartan://localhost:3000/

You should see your index page content.

Step 6: Run the server programmatically

For more control, you can run the server from Python:

import asyncio
from teyaotlani import run_server, ServerConfig

async def main():
    config = ServerConfig(
        host="localhost",
        port=3000,
        document_root="./my-capsule",
        enable_directory_listing=True,
    )

    print(f"Starting server on {config.host}:{config.port}")
    await run_server(config)

asyncio.run(main())

Save this as server.py and run it:

python server.py

Step 7: Enable directory listings

If you want visitors to browse your directory structure, enable directory listings:

config = ServerConfig(
    host="localhost",
    port=3000,
    document_root="./my-capsule",
    enable_directory_listing=True,  # Enable browsing
)

Now visiting a directory without an index file will show its contents.

Step 8: Using a configuration file

For production, use a TOML configuration file. Create config.toml:

[server]
host = "localhost"
port = 3000
document_root = "./my-capsule"
enable_directory_listing = true
index_files = ["index.gmi", "index.gemini"]

[logging]
level = "INFO"

Then load it in Python:

import asyncio
from teyaotlani import run_server, ServerConfig

async def main():
    config = ServerConfig.from_toml("config.toml")
    await run_server(config)

asyncio.run(main())

Or use the CLI:

teyaotlani serve --config config.toml

What you've learned

In this tutorial, you:

  1. Created a capsule with Gemtext content
  2. Ran a Spartan server using the CLI
  3. Ran a server programmatically with run_server()
  4. Enabled directory listings
  5. Used a TOML configuration file

Next steps

Now that you have a working server, you can: