Deploying Atomic Server

Atomic Server is a powerful open-source graph database and headless CMS built on the Atomic Data specification. Written in Rust and powered by actix-web and sled, it delivers exceptional performance with sub-millisecond response times while maintaining an incredibly lightweight footprint—just 8MB with zero runtime dependencies.

Atomic Server combines the connectivity of linked data (RDF) with the simplicity of JSON and the reliability of type-safety. It’s designed for developers who need a flexible, real-time database that can power everything from simple websites to complex collaborative applications.

Lightning Fast

Sub-millisecond response times with full-text search in under 3ms

Real-Time Sync

WebSocket-based live updates for collaborative applications

AI Integration

MCP support with OpenRouter and Ollama compatibility

Type-Safe Data

Schema validation with custom classes, properties, and datatypes

Key Features

Atomic Server provides a comprehensive feature set for modern data management:

Feature	Description
Graph Database	Store and query interconnected data with Atomic Data’s linked structure
Full-Text Search	Fuzzy search with operators, powered by Tantivy
Collaborative Documents	Google Docs-like rich text editing with real-time sync
Tables	Airtable-style spreadsheets with strict schema validation
Group Chat	Built-in messaging with attachments, search, and replies
File Management	Upload, download, and preview file attachments
Version History	Event-sourced versioning with Atomic Commits
Authorization	Fine-grained read/write permissions with hierarchical structures

Why Choose Atomic Server?

Feature	Atomic Server	Traditional CMS	Standard Database
Setup	Single binary, no dependencies	Multiple services	Requires drivers
Real-time	Built-in WebSockets	Plugin required	Manual implementation
Type Safety	Schema enforced	Often loosely typed	Varies by engine
Collaboration	Native support	Third-party tools	Not included
File Size	~8MB	Often 100MB+	Varies

Prerequisites

Before deploying Atomic Server on Klutch.sh, ensure you have:

• A Klutch.sh account with an active project
• A GitHub repository for your deployment configuration
• Basic understanding of Docker and environment variables

Project Structure

Set up your Atomic Server deployment:

• Directoryatomic-server/

  • Dockerfile
  • docker-compose.yml (local development)
  • README.md
  • .env.example

Deployment Configuration

Dockerfile

Create a Dockerfile for your Atomic Server deployment:

Dockerfile

FROM joepmeneer/atomic-server:latest

# Set environment variables for production
ENV ATOMIC_PORT=80
ENV ATOMIC_IP=::
ENV ATOMIC_DATA_DIR=/atomic-storage
ENV ATOMIC_HTTPS=false

# Expose the HTTP port
EXPOSE 80

# Create data directory
RUN mkdir -p /atomic-storage

# Start Atomic Server
CMD ["atomic-server"]

Custom Dockerfile with Environment Configuration

For more control over your deployment:

Dockerfile

FROM joepmeneer/atomic-server:latest

# Production environment variables
ENV ATOMIC_PORT=80
ENV ATOMIC_IP=::
ENV ATOMIC_DATA_DIR=/atomic-storage
ENV ATOMIC_HTTPS=false
ENV RUST_LOG=info

# Create necessary directories
RUN mkdir -p /atomic-storage

# Health check
HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:80/ || exit 1

EXPOSE 80

CMD ["atomic-server"]

Environment Variables

Atomic Server is highly configurable through environment variables:

Variable	Default	Description
ATOMIC_PORT	9883	HTTP port for the server
ATOMIC_PORT_HTTPS	9884	HTTPS port (when enabled)
ATOMIC_IP	::	IP address to bind to
ATOMIC_DOMAIN	localhost	Domain name for the server
ATOMIC_SERVER_URL	Generated	Full URL of the server (set when using external proxy)
ATOMIC_DATA_DIR	OS-dependent	Path for data storage
ATOMIC_HTTPS	false	Enable built-in HTTPS with Let’s Encrypt
ATOMIC_EMAIL	-	Email for Let’s Encrypt certificates
ATOMIC_PUBLIC_MODE	false	Skip authentication (use with caution)
ATOMIC_INITIALIZE	false	Recreate setup invite and rebuild indexes
RUST_LOG	info	Log level (warn, info, debug, trace)

Local Development with Docker Compose

Test your Atomic Server setup locally:

docker-compose.yml

services:
  atomic-server:
    image: joepmeneer/atomic-server:latest
    container_name: atomic-server
    ports:
      - "9883:9883"
    volumes:
      - atomic-storage:/atomic-storage
    environment:
      - ATOMIC_PORT=9883
      - ATOMIC_DATA_DIR=/atomic-storage
      - ATOMIC_DOMAIN=localhost
      - RUST_LOG=info
    restart: unless-stopped

volumes:
  atomic-storage:

Tip

Run docker compose up -d to start Atomic Server locally. Visit http://localhost:9883/setup to create your first admin user.

Deploying to Klutch.sh

1. Push your repository to GitHub

   1. Initialize your Git repository and commit the Dockerfile

   git init
   git add .
   git commit -m "Initial Atomic Server configuration"
   git remote add origin https://github.com/yourusername/atomic-server.git
   git push -u origin main

2. Create a new app on Klutch.sh

   1. Navigate to your Klutch.sh dashboard at klutch.sh/app
   2. Select your project or create a new one
   3. Click Create App and connect your GitHub repository
   4. Klutch.sh will automatically detect your Dockerfile

3. Configure environment variables

   1. In your app settings, add the following environment variables

   Variable	Value
   ATOMIC_PORT	80
   ATOMIC_DATA_DIR	/atomic-storage
   ATOMIC_SERVER_URL	https://your-app.klutch.sh
   ATOMIC_HTTPS	false
   RUST_LOG	info

4. Configure the internal port

   1. Set the internal port to 80
   2. Select HTTP as the traffic type

5. Set up persistent storage

   1. Add a persistent volume for your Atomic Data storage

   Mount Path	Size	Purpose
   /atomic-storage	10 GB	Database, files, configuration

6. Deploy your application

   1. Click Deploy to build and launch your Atomic Server
   2. Monitor the build logs for any issues
   3. Once deployed, your server will be available at https://your-app.klutch.sh

7. Complete initial setup

   1. Visit https://your-app.klutch.sh/setup to create your admin user
   2. Save your Agent Subject and Private Key securely
   3. You can now access the full Atomic Data Browser interface

Important

The ATOMIC_SERVER_URL environment variable must be set to your full Klutch.sh URL (e.g., https://your-app.klutch.sh) since Klutch.sh handles HTTPS termination externally.

Using Atomic Server

Creating Your First Resource

After setup, you can start creating data through the web interface:

1. Click the + New button in the sidebar
2. Choose a resource type (Document, Table, Folder, etc.)
3. Fill in the properties and save

Working with Tables

Atomic Server includes powerful spreadsheet-like tables:

1. Create a new Table resource
2. Define columns with specific datatypes
3. Add rows with validated data
4. Filter, sort, and search your data

Collaborative Documents

Create rich-text documents with real-time collaboration:

1. Create a new Document resource
2. Use the built-in editor with formatting options
3. Share with other users for live editing
4. Track version history through Atomic Commits

Client SDKs

Integrate Atomic Server with your applications using official SDKs:

JavaScript

import { Store, Agent } from '@tomic/lib';

// Initialize the store
const store = new Store({
  serverUrl: 'https://your-app.klutch.sh',
});

// Authenticate with your agent
const agent = Agent.fromSecret('your-private-key');
store.setAgent(agent);

// Fetch a resource
const resource = await store.getResource('https://your-app.klutch.sh/my-resource');
console.log(resource.get('https://atomicdata.dev/properties/name'));

// Create a new resource
const newResource = store.createResource('https://atomicdata.dev/classes/Document');
newResource.set('https://atomicdata.dev/properties/name', 'My Document');
await newResource.save();

React

import { useResource, useStore, useValue } from '@tomic/react';

function MyComponent() {
  const store = useStore();
  const resource = useResource('https://your-app.klutch.sh/my-resource');
  const [name] = useValue(resource, 'https://atomicdata.dev/properties/name');

  if (resource.loading) return <div>Loading...</div>;
  if (resource.error) return <div>Error: {resource.error.message}</div>;

  return <h1>{name}</h1>;
}

Svelte

<script>
  import { getResource } from '@tomic/svelte';

  const resource = getResource('https://your-app.klutch.sh/my-resource');
</script>

{#if $resource.loading}
  <p>Loading...</p>
{:else if $resource.error}
  <p>Error: {$resource.error.message}</p>
{:else}
  <h1>{$resource.props.name}</h1>
{/if}

Installing SDKs

# JavaScript/TypeScript
npm install @tomic/lib

# React
npm install @tomic/react @tomic/lib

# Svelte
npm install @tomic/svelte @tomic/lib

API Reference

Atomic Server provides a RESTful API with JSON-AD responses:

Fetching Resources

# Get a resource as JSON-AD
curl https://your-app.klutch.sh/my-resource \
  -H "Accept: application/ad+json"

# Get as other formats
curl https://your-app.klutch.sh/my-resource \
  -H "Accept: application/ld+json"  # JSON-LD
curl https://your-app.klutch.sh/my-resource \
  -H "Accept: text/turtle"          # Turtle/N-Triples

WebSocket Real-Time Updates

Connect to the WebSocket endpoint for live updates:

const ws = new WebSocket('wss://your-app.klutch.sh/ws');

ws.onopen = () => {
  // Subscribe to a resource
  ws.send(JSON.stringify({
    type: 'subscribe',
    subject: 'https://your-app.klutch.sh/my-resource'
  }));
};

ws.onmessage = (event) => {
  const update = JSON.parse(event.data);
  console.log('Resource updated:', update);
};

Full-Text Search

# Search across all resources
curl "https://your-app.klutch.sh/search?q=your+query"

# Search with filters
curl "https://your-app.klutch.sh/search?q=document&class=https://atomicdata.dev/classes/Document"

Data Backup and Export

Creating Backups

Export your data as JSON-AD for backup:

# Using atomic-server CLI inside the container
docker exec atomic-server atomic-server export > backup.json

Importing Data

Restore from a backup:

# Import with version history
docker exec -i atomic-server atomic-server import < backup.json

# Force import without commits
docker exec -i atomic-server atomic-server import --force < backup.json

Security Best Practices

Agent Keys

Store your Agent Private Key securely—it grants full access to your data

HTTPS

Klutch.sh provides automatic SSL certificates for secure connections

Permissions

Use hierarchical permissions to control read/write access

Regular Backups

Export your data regularly for disaster recovery

Authorization Model

Atomic Server uses a hierarchical authorization system:

1. Resources belong to Parent resources
2. Permissions are inherited down the hierarchy
3. Agents are assigned read/write rights
4. Use Invites to share access with new users

Monitoring and Maintenance

Health Checks

Monitor your Atomic Server instance:

# Check server status
curl https://your-app.klutch.sh/

# View version
curl https://your-app.klutch.sh/app/about

Rebuilding Indexes

If you experience search issues, rebuild indexes:

Dockerfile (rebuild)

# Add to your Dockerfile for one-time rebuild
ENV ATOMIC_REBUILD_INDEX=true

Or run manually:

docker exec atomic-server atomic-server --rebuild-indexes

Troubleshooting

Common issues and solutions:

Issue	Cause	Solution
Setup page not loading	Wrong ATOMIC_SERVER_URL	Ensure URL matches your Klutch.sh domain
Authentication failures	Agent key mismatch	Verify your private key and agent subject
Search not returning results	Index out of sync	Run --rebuild-indexes
WebSocket disconnections	Network timeouts	Check client reconnection logic
Data not persisting	Volume not mounted	Verify /atomic-storage mount path

Viewing Logs

Check server logs for debugging:

# Set verbose logging
ENV RUST_LOG=debug

Advanced Configuration

Custom Scripts

Inject custom JavaScript into the frontend:

ENV ATOMIC_SCRIPT="console.log('Custom script loaded');"

AI Integration

Enable AI features with MCP support:

# Configure AI backend (requires external service)
ENV ATOMIC_AI_PROVIDER=openrouter
ENV ATOMIC_AI_API_KEY=your-api-key

Additional Resources

• Atomic Data Demo
• Atomic Data Documentation
• Atomic Server GitHub Repository
• Atomic Data Discord Community
• @tomic/lib NPM Package
• @tomic/react NPM Package
• @tomic/svelte NPM Package