AsmBB is high performance web forum software, written entirely in assembly language. It is very lightweight, but provides decent set of features and ultimate performance.

The current version of AsmBB is v2.0;

The easiest way to install AsmBB is to download the binary package.

Download the package from this link: asmbb.tar.gz (it is permanent link to the latest trunk version of the package).

It contains the file install.txt with directions for installation on shared hosting.

For installation on dedicated servers or VPS, reference the following article: "How to install AsmBB on vps with nginx and systemd"

The content of install.txt follows:

install.txt

AsmBB installation guide

Preface

This package contains the forum engine AsmBB, which is high performance web forum engine, written entirely in assembly language.

This package is the binary release of the engine, but it is free open source distributed under EUPL license (the file License.txt) and you can download the source code from the source repository (fossil), located on:

http://asm32.info/fossil/repo/asmbb/

Prerequisites

In order to use AsmBB you will need running web server, supporting FastCGI protocol. Most web servers will do the job. Particularly Apache.

You can install AsmBB on local server (for testing) on shared hosting or any other hosting option.

The only mandatory condition is that the server must run on x86 or x86-64 Linux platform and the fastcgi module should be enabled (most servers running php has it enabled anyway).

AsmBB is self sufficient and does not requires any libraries or databases installed on the server.

In order to send mails to the forum users, AsmBB will need the address and port number of SMTP server that is accessible from your web server without authentication. Most SMTP servers provided by the web hosting will not need authentication if connected from the local network (i.e. the web site engine).

Installation

First unpack the files in temporary directory. Depending on your server edit the file .htaccess (Apache) or lighttpd.conf (lighttpd) - Change the "_FULL_PATH_TO_DOCUMENT_ROOT_HERE_" placeholder to the real path to your document root (it depends on the web server settings).

IMPORTANT: Ensure that the uploaded files have the proper permissions for the www-data user (the web server user). The www-data user will need writing permissions in the DOCUMENT_ROOT directory. The executable files must have 755 permissions.

IMPORTANT FOR Lighttpd: The provided in the package file "lighttpd.cond is just an example. Lighttpd keeps its config files in: "/etc/lighttpd/lighttpd.conf" and all files in "/etc/lighttpd/conf-enabled/" directory. You will need to merge the example config in the existing files in one or another consistent way and then restart lighttpd.

If using another web server, prepare the configuration by yourself.

Upload all files (directories and symlinks) of the package to the document_root directory of your web server.

IMPORTANT: The package may contain some symlinks. Ensure they are uploaded together with the files. Notice, that FTP can't upload symlinks.

The simplest way is to upload the tarball to the server and unpack there by using cpanel tools, ssh or any other way.

Read the chapter "Easy Installation on Apache by FTP" below, about how to make the proper upload by FTP.

Test the forum by loading the web site in your favorite browser.

As simple as that.

Easy Installation on Apache by FTP

Download the package "unpack.tar.gz" from:

http://asm32.info/fossil/repo/asmbb/doc/trunk/install/unpack.tar.gz

Untar it. There are 2 files: ".htaccess" and "unpack.sh";

Upload these 2 files and "asmbb.tar.gz" on the server document_root via ftp or any other way. The root directory must contain these 3 files:

.htaccess asmbb.tar.gz unpack.sh

Load in some browser: http://your_web_size/unpack.sh

The script will unpack all files, prepare the proper .htaccess file and redirect you to the new created forum working in setup mode.

Introduction to the forum configuration.

When run for the first time, AsmBB will create an empty database for the forum - a file, named board.sqlite in the root directory.

Until there is no users registered, AsmBB will run in setup mode, displaying the administrator user creation dialog.

The registration of the admin user will not need email activation and is pretty liberal about the quality of the password. But you as an administrator of the forum, better choose strong password and whatever nickname you prefer.

After creation the administrator user, the access to the forum settings is restricted only for the users with administrator privileges.

Set the SMTP server and other forum parameters in the settings page.

AsmBB advanced manual

Downloading the sources of AsmBB.

AsmBB is hosted in fossil version control system on AsmBB repository.

The best way to get the source code of AsmBB is to clone the repository (you will need fossil installed on your system).

Type in the console:

$ fossil clone https://asm32.info/fossil/repo/asmbb  /%path_to_repositories%/asmbb.fossil

Then create checkout:

$ mkdir asmbb
$ cd asmbb
$ fossil open /%path_to_repositories%/asmbb.fossil

Now you have all files from the branch trunk in the /asmbb directory. If you want the code from some other branch, execute:

$fossil co %BRANCH_NAME%

Downloading the dependencies.

In order to compile AsmBB you will need:

The sources of FreshLibDev

Cloning and checkout is very similar to the same procedure for AsmBB:

$ fossil clone https://fresh.flatassembler.net/fossil/repo/fresh  /%path_to_repositories%/Fresh.fossil
$ mkdir FreshLibDev
$ cd FreshLibDev
$ fossil open /%path_to_repositories%/Fresh.fossil FreshLibDev

Installation and settings of Fresh IDE:

The installation of Fresh IDE is described in details in the Fresh IDE setup manual.

After installing Fresh IDE, set the lib alias (Options|IDE options|Aliases) to point to the "FreshLibDev/freshlib/" directory.

Compiling AsmBB

Now you are ready to compile AsmBB.

Open the file AsmBB/source/engine.fpr (the project file) in Fresh IDE and press Ctrl+F9.

If the compilation complete without errors, the compiled binary is AsmBB/www/engine.

Deploying AsmBB on the server.

Needed files that need to be placed on the server are:

templates/* - contains all HTML templates needed by the engine.

images/* - contains all images needed by the forum. The specific images are only depending on the templates and the .css files. The engine itself does not hardcode the image files.

all.css - contains the CSS code. The name of this file is specified in templates/main_html_start.tpl and may vary if the templates has been changed.

engine - the forum engine.

libsqlite3.so - the SQLite library. In order to work on 64bit servers, this file has been statically linked and compiled with musl library.

ld-musl-i386.so - the MUSL dynamic linker, needed for loading libraries on 64bit servers.

Some notes on the forum engine structure

The table "Params"

The table "Params" contains name/value pairs for the global forum settings. The table is defined following way:

create table Params (
  id  text primary key,
  val text
);

Here are some parameters used in the current version of the forum engine. The parameters, marked as "Mandatory!" must be set during the installation of the forum engine.

"host" - string; Mandatory! The domain name of the forum.

"smtp_addr" - string; Mandatory! The URL or IP address of the smtp server used to send the user activation emails. This address should be on the same host (see "host" above) as the forum itself, or should allow sending emails without authentication.

"smtp_port" - integer; Mandatory! The port (the usual is 25, but can vary) of the smtp server.

"smtp_user" - string; Mandatory! The email account of the email sender (the administrator email). The whole email address of the sender should be \smtp_user\@\host\ or \smtp_user\@\smtp_addr\

"page_length" - integer (default: 20); The number of items, grouped in pages (both posts in a thread and threads in the thread list).

"log_events" - integer (flag (0, 1), default: 0); When 1 enables the logging mechanism of the forum. The logging is useful for debugging, but slows down the engine.

"forum_title" - string (default: "AsmBB"; The initial part of the forum title, as displayed in the browser title bar. Some suffix parts are added to this string (for example the current thread title) to form the result title of the current page.

"user_perm" - integer (default: 29); Bit-mask, indicating the initial permissions the user have after registration. Later the individual permissions can be edited for the individual users. The permissions are defined in the beginning of the "commands.asm" and currently are:

permLogin       = 1
permPost        = 4
permThreadStart = 8
permEditOwn     = 16
permEditAll     = 32
permDelOwn      = 64
permDelAll      = 128
permAdmin       = $80000000

"avatar_max_size" - integer (default: 50KB); The maximal size of the user uploaded images in bytes.

"avatar_width" - integer (default: 128px); The width of the user uploaded avatars. Avatars with different width are rejected. Notice, that the avatars already uploaded to the database will not be affected by the change of this parameter.

"avatar_height" - integer (default: 128px); The height of the user uploaded avatars. Avatars with different height are rejected. Notice, that the avatars already uploaded to the database will not be affected by the change of this parameter.

More important of these parameters can be set from the /!settings (settings panel) of the forum.

The remaining should be set from the SQLite console. Something like:

  insert or replace into Params values ("avatar_max_size", 10*1024);

The parameter can be deleted by:

  delete from Params where id="avatar_max_size";

The whole content of the table can be displayed by:

  select * from Params;

Templates

Introduction

The templates are text files, with extension ".tpl" located in the directory "/templates". They contains some text, mixed with special commands, interpreted by the forum engine in order to create the HTML code of the pages, sent to the user.

By editing the template files, it is possible to change the appearance of the forum to any desirable visual skin.

The commands are enclosed in square brackets and can be nested recursively. Each command in fact returns some text value, replacing the command itself.

The template engine is always called with 2 (optional) parameters:

1. Active SQLite statement, containing one row of some SQL query and

2. Pointer to an array of engine internal variables about the currently served HTTP request.

This way, the commands are two types - commands returning information from the internal data structures of the engine and commands returning information from the SQL statement.

Commands returning request information

[special:KEYWORD] It is group of commands, returning information from the internal data structure.

Depending on KEYWORD, there are:

[special:version] - Returns the version of the engine executable file.

[special:timestamp] - Returns the time elapsed from the beginning of the current HTTP request, formatted as a decimal number with 3 digits after the decimal point. The time is measured in milliseconds with resolution in microseconds.

[special:title] - Returns the full current page title.

[special:username] - Returns the username of the user that made the request, or empty string if the user is not logged in.

[special:userid] - Returns the ID of the user (as in Users table of the database) that made the request, or 0 if the user is not logged in.

[special:permissions] - Returns the permissions of the user that made the request. If the user is not logged in - returns 0.

[special:isadmin] - 1 if the user is admin. 0 - if not admin or not logged in.

[special:canlogin] - 1 if the user is permitted to login. Currently, it is always 1, but in the future versions is possible to be used to ban users by IP.

[special:canpost] - 1 if the user is permitted to post messages in existing threads.

[special:canstart] - 1 if the user is permitted to start new threads.

[special:canedit] - 1 if the user can edit the currently displayed post. 0 elsewhere. This flag is a little bit tricky. It will be 1 only if the user has global editing permission or if the current SQL statement, passed to the template engine has field "userid" equal to the userid of the current user and this current user has editing permissions for its own content.

[special:candel] - 1 if the user can delete the currently displayed post. See [special:canedit] for detailed explanation.

[special:page] - Returns the number of the page, as specified in the requested URL or 0 if no page is specified. It has meaning only for the thread lists and threads pages.

[special:dir] - Returns the current directory (in other words the current selected tag) as specified in the requested URL.

[special:thread] - Returns the slug of the thread as specified in the request URL. Has meaning only for threads.

[special:referer] - Returns the page from where the user came. i.e. the HTTP_REFERER header of the request.

[special:alltags] - Returns all tags, of the forum, that have at least 1 thread attached, formatted in HTML with sizes, proportional to their popularity (i.e. the number of threads tagged with every tag). This command is aimed especially to construct the tag list displayed at the top of the pages. Can be styled by CSS or/and JS if needed.

[special:setupmode] - Special tag, that has value of 1 only when the forum is in setup mode, i.e. the Users table is empty. In this mode, only the admin created form is displayed by the forum. Should not be used in the templates actually.

[special:search] - Returns the current search query of the forum search engine.

[special:posters=THREAD_ID] - Returns list of the usernames of the thread starter and first several posters in the thread with ID=THREAD_ID. Can be used in the thread list summary representation of the thread. The list is formatted in HTML.

[special:threadtags=THREAD_ID] - Similar to the previous command, returns a list of the tags, assigned to a thread with ID=THREAD_ID.

Commands for data processing

[minimag:MARKDOWN_TEXT] - This command parses the markdown formatted text MARKDOWN_TEXT and converts it into HTML. The markup is very similar to the base markdown, but has some differences.

[case:INDEX|TEXT0|TEXT1|TEXT2..|TEXTN] - case operator, depending on the value of INDEX, one of the "|" delimited texts is returned. The operator works with saturation. If the value of INDEX is bigger than the number of provided texts, the last text is returned.

[sql:SQL_STATEMENT|PARAM1|PARAM2|...|PARAMN] - Prepares SQL statement SQL_STATEMENT, binds the "?" parameters to the provided, "|" separated values and executes the query. The query must be scalar - i.e. to return only one value and this value is returned as a result of the operation. If the query ends with empty set or error, an empty string is returned. Notice: this is extremely dangerous command that can destroy the data base! Use only "select" statements and always use fixed query and parameter bindings.

Actually this command is usually used not for extracting data from the database, but simply as a calculator to compute complex expressions by using the SQLite expression parser. In this case the command looks like:

[sql: select EXPRESSION|PARAM1|PARAM2...|PARAMN]

and is safe for use, because does not access the database at all.

SQL statement data fields.

The fields of the SQL statement passed to the template are replaced by simply enclosing the field name in square brackets.

For example [username] will return the value of the field "username" from the statement if such field exists.

If such field does not exists, the command is not replaced at all.

Every template file has its own different SQL query that is passed to it with its own set of accessible database fields.

The fields will be described with the description of the particular template files.

Template files used in the present version

The template files that the present versions of the engine use are:

"main_html_start" - this is the main forum HTML header.

"main_html_end" - this is the main forum HTML footer.

Every visible page in the forum is formed by concatenation of "main_html_start", then one or more from the other templates, described below and then "main_html_end" at the end.

Both templates has no access to the database fields.

"error_html_start" - the header part of the generated HTML on error pages.

"error_html_end" - the footer of the generated HTML on error pages (i.e. these for 404, and other HTTP error pages).

Both error header and footer templates has no access to database fields. These templates are very similar to the previous two, but are used for the error page rendering.

"activation_email_subject" - This is the text of the "subject" field of the activation email, sent to the user during his registration or email change notification.

"activation_email_text" - The text of the registration (or email change) activation message.

The accessible query fields are the same for the above two templates and are selected from the table WaitingActivation:

id - the ID in the table WaitingActivation

nick - the nickname of the user as registered.

email - the email address of the user.

secret - the activation secret token. 32 characters random string.

salt - 32 characters random string, salt for the password of the user. It is useful because it has some value only on user registration. On email address change, the value is NULL.

host - the host of the forum, extracted from the table "Params"

Some of these fields can be used for personalizing the email for the particular use. Some simple example for the subject template is:

[case:[salt]|Email change confirmation for http://[host]|Account activation link for http://[host]]

-

"form_login" - Provides the HTML form for user login.

"form_register" - Provides the HTML form for new user registration.

"form_setup" - this form is displayed only when the forum is in setup mode (i.e. empty Users table). It provides dialog for the first admin user registration.

These three forms has no access to the database fields.

-

"del_confirm" - It provides the confirmation dialog on message deletion.

The accessible fields are: PostID, ThreadID, UserName, UserID, Content, cnt_thread (the total count of the posts in the thread, before deletion), Slug - mixed fields for the post, thread and the owner of the post.

-

"form_edit" - the form for editing post.

Has access to the following data fields from the Posts and Threads tables:

id - the ID of the post in the table Posts

caption - the caption of the thread.

source - the MiniMag (markdown) formatted text of the post

ticket - Unique string, serves as a bot protection. Guarantees that the user loads the form from the server and does not try to post using some script. This ticked must be later posted to the forum engine in a hidden input, named "ticket".

-

"userinfo" - this template displays the user profile information readable for all users, i.e. the content of the page /!userinfo/USERNAME.

"form_editinfo" - this template provide the forms for editing user profile information. It will be rendered only for the users that have editing access for the given profile - the owner of the account and the admin users.

The accessible DB fields for both above templates are:

UserID, UserName - the ID and UserName of the user which profile is displayed.

AVer - the version of the user avatar. A number, changed each time the user changes its avatar image.

status - the user permissions.

user_desc - The information about the user, formatted in markdown, that to be displayed in the profile.

LastSeen - The date and time, the user has been last seen in the forum. Formatted as '%d.%m.%Y %H:%M:%S'.

TotalPosts - The total number of posts in the forum.

The permission flags: CanLogin, CanPost, CanStart, CanEditOwn, CanEditAll, IsAdmin - can have values 0 or 1.

-

"form_new_thread" - the form for creating new thread. Besides the post text, provides editing of the thread title and the tags, attached to the thread.

"form_new_post" - the form for answering in already existing thread. It allows editing only of the message, but not of the thread title or thread tags.

"preview" - provides the preview of the post, when the user presses "Preview" button.

All these 3 templates has access to the following DB fields:

slug - the short version of the thread caption, used in the URL.

caption - the thread caption.

source - the text of the post.

ticket - the server set ticked for bot protection.

tags - the tags, attached to this thread.

-

"form_settings" - the form providing editing of the forum settings. Has access to the following fields from the table "Params" (described above):

host, smtp_addr, smtp_port, smtp_user, forum_title, log_events, page_length, user_perm0, user_perm2, user_perm4, user_perm5, user_perm6, user_perm7 and user_perm31;

The user_permN fields are simply the bits from the status fields.

Also, there are the fields message and error which are the error message and error flag from the previous attempt to save the settings.

"form_sqlite_console" - this is the SQLite console form.

It has access to a single field source containing the SQL statement(s) that to be executed.

"minimag_suffix" - this template will be added to the end of every text, formatted by MiniMag (markdown). Can be used for creation of predefined links for the easier access. This way in the forum are defined the smile images.

-

"nav_list" - The navigation buttons displayed at the top and bottom of the pages, when the thread list is displayed.

"nav_search" - The navigation buttons when the search result page is displayed.

"nav_thread" - The navigation buttons when the posts in the thread are displayed.

"post_view" - this template is rendered for every single post in a thread. Has access to the following DB fields:

ID, ThreadID, Slug - IDs of the post and the thread, the slug of the thread.

PostTime - Formatted time of the last post edit.

Content - the text of the post.

UserID, UserName, UserPostCount, AVer - Information for the user that posted this post.

Unread - flag, whether the post is unread for the current user

ReadCount - how many times the post has been rendered until now.

"thread_info" - This template is rendered for every thread in the thread list. Has access to the following DB fields:

ID, Slug, Caption - the thread attributes.

Pinned - whether the thread is pinned at the top of all threads in the list.

TimeChanged - the time thread was latest changed.

PostCount - the number of the posts in the thread.

Unread - how many posts from this thread are not read by the current user.

"search_result" - Rendered for every post found from the forum search engine when the search results are displayed. Has access to the following fields:

UserID, UserName, Caption, Slug, PostTime, ReadCount, Unread - common information for the post and for the thread.

Content - this is only short snippet of the original post text, aimed to provide preview to the user. The snippet always contains the keyword that has been searched.

The binary package (the link in the first post) has been updated to v1.3;

The binary package has been updated to v1.5 with improved skin support.

The binary packages has been updated to v1.7

The binary package has been updated to v2.0