Deploying AsmBB

AsmBB is a high-performance web forum engine written entirely in assembly language using FlatAssembler (FASM). Renowned for its extreme efficiency and minimal resource usage, AsmBB can serve massive amounts of visitors on even the most modest hardware. With page processing times measured in milliseconds and a self-contained architecture using SQLite for data storage, AsmBB represents the ultimate in lightweight forum software.

Built for speed and simplicity, AsmBB uses the FastCGI interface to communicate with web servers and requires no external dependencies beyond a web server with FastCGI support. This guide walks you through deploying AsmBB on Klutch.sh using Docker with Nginx as the web server.

Why Choose AsmBB?

Blazing Fast

Written in pure assembly language, AsmBB delivers page processing times of just 3-80 milliseconds.

Minimal Resources

Runs efficiently on the cheapest VPS or shared hosting, handling thousands of visitors without lag.

Self-Contained

Uses embedded SQLite database with no external dependencies—everything runs in a single lightweight process.

Secure

Aggressive testing and minimal attack surface result in excellent security with optional database encryption.

Prerequisites

Before deploying AsmBB on Klutch.sh, ensure you have the following:

• A GitHub account for repository hosting
• A Klutch.sh account for deployment

Key Features

AsmBB provides a comprehensive feature set despite its minimal footprint:

Core Features

• Thread-based discussions: Traditional forum structure with threads and posts
• User management: Registration, login, avatars, and user profiles
• MiniMag markup: Markdown-like syntax for post formatting
• Tag system: Organize threads with customizable tags
• Search functionality: Full-text search across all posts
• Real-time chat: Built-in chat functionality
• RSS feeds: Subscribe to forum updates

Administration Features

• Settings panel: Configure forum through web interface
• User permissions: Granular permission system for posting, editing, and administration
• SQLite console: Direct database access for advanced administration
• Customizable templates: Full control over forum appearance
• SMTP integration: Email notifications for user registration

Technical Features

• FastCGI interface: Works with Nginx, Apache, Lighttpd, and more
• SQLite database: Self-contained, no external database required
• SQLeet encryption: Optional database encryption for enhanced security
• x86/x86-64 Linux: Native binary runs on any x86 Linux system

Architecture Overview

AsmBB uses a FastCGI architecture where:

┌─────────────────────────────────────────────────────────────────────┐
│                          Client Browser                              │
└──────────────────────────────┬──────────────────────────────────────┘
                               │ HTTP/HTTPS
                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         Nginx Web Server                             │
│                     (Reverse Proxy + FastCGI)                        │
└──────────────────────────────┬──────────────────────────────────────┘
                               │ FastCGI (Unix Socket)
                               ▼
┌─────────────────────────────────────────────────────────────────────┐
│                         AsmBB Engine                                 │
│                    (Assembly Binary + SQLite)                        │
│  ┌──────────────────────────────────────────────────────────────┐   │
│  │                     board.sqlite                              │   │
│  │                   (Forum Database)                            │   │
│  └──────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────┘

Project Structure

Create the following structure for your AsmBB deployment:

asmbb-deploy/
├── Dockerfile
├── nginx.conf
├── supervisord.conf
├── start.sh
└── README.md

Creating the Dockerfile

AsmBB requires a custom Dockerfile that sets up both Nginx and the AsmBB engine. Create a Dockerfile in your project root:

Dockerfile

FROM debian:bullseye-slim

# Install dependencies
RUN apt-get update && apt-get install -y \
    nginx \
    supervisor \
    wget \
    curl \
    ca-certificates \
    && rm -rf /var/lib/apt/lists/*

# Create AsmBB directory
RUN mkdir -p /var/www/asmbb

# Download and extract AsmBB
WORKDIR /var/www/asmbb
RUN wget -q https://asm32.info/fossil/repo/asmbb/doc/trunk/install/asmbb.tar.gz \
    && tar -xzf asmbb.tar.gz \
    && mv asmbb/* ./ \
    && rm -rf asmbb asmbb.tar.gz \
    && rm -f *.txt lighttpd.conf .htaccess

# Set proper permissions
RUN chown -R www-data:www-data /var/www/asmbb \
    && chmod +x /var/www/asmbb/engine

# Copy configuration files
COPY nginx.conf /etc/nginx/nginx.conf
COPY supervisord.conf /etc/supervisor/conf.d/supervisord.conf
COPY start.sh /start.sh
RUN chmod +x /start.sh

# Create necessary directories
RUN mkdir -p /var/log/nginx /var/log/supervisor /run/nginx

# Expose the web port
EXPOSE 8080

# Health check
HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
    CMD curl -f http://localhost:8080/ || exit 1

CMD ["/start.sh"]

Binary Package

AsmBB provides pre-compiled binaries that run on x86/x86-64 Linux systems. The binary package includes all necessary files including the SQLite library statically linked with musl libc.

Creating the Nginx Configuration

Create an nginx.conf file for the FastCGI configuration:

nginx.conf

user www-data;
worker_processes auto;
pid /run/nginx.pid;
error_log /var/log/nginx/error.log;

events {
    worker_connections 1024;
    use epoll;
    multi_accept on;
}

http {
    include /etc/nginx/mime.types;
    default_type application/octet-stream;

    # Logging
    access_log /var/log/nginx/access.log;

    # Performance optimizations
    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 65;
    types_hash_max_size 2048;

    # Gzip compression
    gzip on;
    gzip_vary on;
    gzip_proxied any;
    gzip_comp_level 6;
    gzip_types text/plain text/css text/xml application/json application/javascript application/rss+xml application/atom+xml image/svg+xml;

    server {
        listen 8080;
        server_name _;

        root /var/www/asmbb;

        # Serve static files directly
        location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg|woff|woff2|ttf|eot)$ {
            expires 30d;
            add_header Cache-Control "public, immutable";
            try_files $uri =404;
        }

        # FastCGI to AsmBB engine
        location / {
            fastcgi_pass unix:/var/www/asmbb/engine.sock;
            include fastcgi_params;

            # FastCGI parameters
            fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
            fastcgi_param PATH_INFO $fastcgi_path_info;
            fastcgi_param SERVER_NAME $host;

            # Timeouts
            fastcgi_connect_timeout 60;
            fastcgi_send_timeout 180;
            fastcgi_read_timeout 180;
            fastcgi_buffer_size 128k;
            fastcgi_buffers 4 256k;
            fastcgi_busy_buffers_size 256k;
        }

        # Security headers
        add_header X-Frame-Options "SAMEORIGIN" always;
        add_header X-Content-Type-Options "nosniff" always;
        add_header X-XSS-Protection "1; mode=block" always;
    }
}

Creating the Supervisor Configuration

Create a supervisord.conf file to manage both Nginx and the AsmBB engine:

supervisord.conf

[supervisord]
nodaemon=true
user=root
logfile=/var/log/supervisor/supervisord.log
pidfile=/var/run/supervisord.pid
childlogdir=/var/log/supervisor

[program:asmbb]
command=/var/www/asmbb/engine
directory=/var/www/asmbb
user=www-data
autostart=true
autorestart=true
startsecs=5
startretries=3
stdout_logfile=/var/log/supervisor/asmbb.log
stderr_logfile=/var/log/supervisor/asmbb_error.log
priority=100

[program:nginx]
command=/usr/sbin/nginx -g "daemon off;"
autostart=true
autorestart=true
startsecs=5
startretries=3
stdout_logfile=/var/log/supervisor/nginx.log
stderr_logfile=/var/log/supervisor/nginx_error.log
priority=200

Creating the Startup Script

Create a start.sh script to initialize the environment:

start.sh

#!/bin/bash
set -e

# Set ownership
chown -R www-data:www-data /var/www/asmbb

# Remove stale socket if exists
rm -f /var/www/asmbb/engine.sock

# Start supervisor (which manages nginx and asmbb)
exec /usr/bin/supervisord -c /etc/supervisor/conf.d/supervisord.conf

Deploying to Klutch.sh

1. Create a GitHub repository

   Create a new repository for your AsmBB deployment:

   mkdir asmbb-deploy
   cd asmbb-deploy
   git init

2. Add all configuration files

   Create all the files described above:

   • Dockerfile
   • nginx.conf
   • supervisord.conf
   • start.sh

3. Push to GitHub

   Commit and push your repository:

   git add .
   git commit -m "Initial AsmBB deployment configuration"
   git branch -M main
   git remote add origin https://github.com/yourusername/asmbb-deploy.git
   git push -u origin main

4. Connect to Klutch.sh

   Navigate to klutch.sh/app and sign in with your GitHub account. Click New Project to begin the deployment process.

5. Select your repository

   Choose the GitHub repository containing your AsmBB Dockerfile. Klutch.sh will automatically detect the Dockerfile in your project root.

6. Set the internal port

   Configure the internal port to 8080 (the port Nginx listens on in our configuration).

7. Add persistent storage

   AsmBB stores all forum data in a SQLite database. Add a persistent volume to preserve your forum data:

   Mount Path	Size
   /var/www/asmbb	1 GB+

   Persistent Storage Required

   Without persistent storage, all forum data including posts, users, and configuration will be lost when the container restarts. Always configure a persistent volume for production use.

8. Deploy your application

   Click Deploy to start the deployment process. Once complete, your AsmBB forum will be accessible at https://example-app.klutch.sh.

First-Time Setup

When you first access your AsmBB forum, you’ll be greeted with the setup wizard:

1. Access your forum

   Navigate to your deployed AsmBB URL (e.g., https://example-app.klutch.sh). The admin setup dialog will appear automatically.

2. Create the administrator account

   Fill in the administrator registration form:

   • Username: Choose your admin username
   • Password: Select a strong password
   • Email: Your admin email address

   First User

   The first user registered becomes the administrator. Choose a strong password as this cannot be changed without direct database access.

3. Configure forum settings

   After creating the admin account, access the settings panel at /!settings to configure:

   • Forum title: Your forum’s name
   • SMTP settings: For user registration emails
   • User permissions: Default permissions for new users

Forum Configuration

Essential Settings

Access the settings panel at https://example-app.klutch.sh/!settings to configure:

Setting	Description	Example
host	Your forum’s domain name	example-app.klutch.sh
forum_title	Title displayed in browser	My AsmBB Forum
smtp_addr	SMTP server address	smtp.gmail.com
smtp_port	SMTP server port	587
smtp_user	Email sender username	noreply
page_length	Posts per page	20

User Permissions

AsmBB uses a bitmask-based permission system:

Permission	Value	Description
permLogin	1	Ability to log in
permPost	4	Post in existing threads
permThreadStart	8	Create new threads
permEditOwn	16	Edit own posts
permEditAll	32	Edit all posts
permDelOwn	64	Delete own posts
permDelAll	128	Delete all posts
permAdmin	2147483648	Administrator access

Default user permissions are typically set to 29 (login + post + thread start + edit own).

SQLite Console

For advanced administration, access the SQLite console at /!sqlite (admin only). Example queries:

-- View all forum parameters
SELECT * FROM Params;

-- Update a parameter
INSERT OR REPLACE INTO Params VALUES ('forum_title', 'My Awesome Forum');

-- View user count
SELECT COUNT(*) FROM Users;

-- List recent threads
SELECT * FROM Threads ORDER BY id DESC LIMIT 10;

Database Access

Be careful when using the SQLite console. Incorrect queries can corrupt your forum data. Always backup before making changes.

Customizing Templates

AsmBB uses a template system located in the /templates directory. Key template files:

Template	Purpose
main_html_start.tpl	HTML header for all pages
main_html_end.tpl	HTML footer for all pages
thread_info.tpl	Thread listing appearance
post_view.tpl	Individual post display
form_login.tpl	Login form
form_register.tpl	Registration form

Template Variables

Templates support special commands in square brackets:

<!-- Display the forum title -->
<title>[special:title]</title>

<!-- Show current user -->
Welcome, [special:username]!

<!-- Check if user is admin -->
[case:[special:isadmin]|User|Admin]

<!-- Display processing time -->
Page rendered in [special:timestamp] ms

MiniMag Markup

AsmBB uses MiniMag, a Markdown-like syntax for formatting posts:

Syntax	Result
*bold*	bold
/italic/	italic
_underline_	underline
-strikethrough-	strikethrough
[link text|url]	Hyperlink
[image.jpg]	Image
#header	Header
##subheader	Subheader
`code`	Inline code
>>>quote	Blockquote

Custom Domain Setup

To use a custom domain with your AsmBB deployment:

1. Add your domain in Klutch.sh

   Navigate to your project settings and add your custom domain (e.g., forum.yourdomain.com).

2. Configure DNS records

   Add a CNAME record pointing to your Klutch.sh deployment:

   Type	Name	Value
   CNAME	forum	example-app.klutch.sh

3. Update forum settings

   Update the host parameter in AsmBB settings:

   INSERT OR REPLACE INTO Params VALUES ('host', 'forum.yourdomain.com');

4. Wait for SSL provisioning

   Klutch.sh automatically provisions SSL certificates for custom domains.

Local Development with Docker Compose

For local development and testing:

docker-compose.yml

services:
  asmbb:
    build: .
    ports:
      - "8080:8080"
    volumes:
      - asmbb-data:/var/www/asmbb
    restart: unless-stopped

volumes:
  asmbb-data:

Start the local environment:

docker compose up -d

Access AsmBB at http://localhost:8080.

Performance Optimization

AsmBB is already extremely optimized, but you can further enhance performance:

Nginx Caching

Add caching for static assets in nginx.conf:

# Browser caching for static files
location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg)$ {
    expires 30d;
    add_header Cache-Control "public, immutable";
    add_header Vary Accept-Encoding;
}

Database Optimization

Periodically optimize the SQLite database:

VACUUM;
ANALYZE;

Backup and Restore

Creating Backups

The forum data is stored in /var/www/asmbb/board.sqlite. To backup:

1. Access your container or use Klutch.sh backup features
2. Copy the board.sqlite file
3. Optionally backup templates and images directories

Restoring from Backup

1. Stop the AsmBB engine
2. Replace board.sqlite with your backup
3. Restart the engine

Troubleshooting

Forum Not Loading (502 Bad Gateway)

This usually means the AsmBB engine isn’t running or the socket isn’t created:

1. Check supervisor logs: /var/log/supervisor/asmbb_error.log
2. Verify socket exists: /var/www/asmbb/engine.sock
3. Check permissions on the AsmBB directory

Email Not Sending

Verify SMTP settings in the forum configuration:

1. Access /!settings as admin
2. Verify smtp_addr, smtp_port, and smtp_user are correct
3. Ensure your SMTP server allows connections from your deployment

Database Locked Errors

If you see database locked errors:

1. This may occur during heavy load
2. Consider increasing SQLite busy timeout
3. Ensure only one AsmBB instance is running

Slow Performance

AsmBB is designed to be fast, but if performance degrades:

1. Check database size with ls -la board.sqlite
2. Run VACUUM and ANALYZE in SQLite console
3. Verify sufficient memory in your deployment

Resources

• AsmBB Fossil Repository
• Official AsmBB Demo & Support Forum
• Installation Documentation
• VPS Installation Guide
• FlatAssembler (FASM)

Next Steps

After deploying AsmBB, consider:

• Customizing templates to match your brand
• Configuring SMTP for user registration emails
• Setting up categories and tags for organization
• Creating moderator accounts with appropriate permissions
• Enabling database encryption for sensitive forums
• Setting up regular database backups