Prerequisites for Installation

In this chapter we describe the necessary prerequisites for installing Focus™.

Client-side

One of the modern operating systems in reasonably-recent versions (Windows, MacOS, Linux, iOS, Android).
One of the modern browsers in reasonably-recent versions (Firefox, Chrome, Safari, Edge).
Good old Internet Explorer is NOT supported (for various security and imcompatibility reasons of versions still in use).

Hosting

Focus™ requires a physical, virtual or containerized server to install on.
For personal, small group or test installations, it can also be installed to a desktop or notebook, but for serious production installations we recommend a proper server hosting platform.
Any of the cloud-based or bare-metal-based offerings on the market are fine.

Architecture

Any modern CPU architecture, on which a Go™ compiler is available, can be used.
This includes Intel, AMD, ARM and others.

Operating System

Focus™ has been developed on a declarative Linux operating system (NixOS) and is officially supported only on Linux in general.
Due to its Go-based nature, it runs equally well on BSD™, Windows™, MacOS™ or even exotic operating systems (e.g. Haiku™).

Go™ Compiler

You will need an installed version of the Go™ compiler (1.17 or above).

SQL Database

Focus™ needs to access an installed version of MySQL or MariaDB with enabled local access by TCP/IP (127.0.0.1) and the associated database server “root” account & password.
During the installation, you will create a dedicated database user for Focus™ and the required "focus" database.

E-Mail Server

You require an installed SMTP-capable e-mail server (eg. Exim4), which is configured to receive SMTP-based e-mail via port 25 from “localhost” and capable of sending e-mail to other SMTP servers on the Internet (needed for registration of new players or recovering a lost certificate).
Optionally you will need an installed IMAP e-mail server (e.g. Dovecot), which is configured to retrieve e-mail messages by IMAP protocol via port 143 from “localhost” with plain text authentication (only needed, if you for example want to provide a feedback email address etc.).
For both, you could also use one of the offerings from cloud providers (outlook.com, google.com, etc).

Memory and Disk Space

We recommend to have at least 4 GB of main memory available and about 32 GB of disk space.
In general: the more the better (as free memory is used for file caching).
Memory and disk space requirements naturally scale and vary greatly with the number of parallel users and the amount of data stored in Focus™, so we recommend to closely observe these two parameters for your individual use case and extend on an "as needed" basis.

User Access

Focus™ can be installed with user privileges on an operating system.
For serious production installations you will need "root" or "administrator" access, as you will typically install an SSL proxy server in front of Focus™ to further harden security.
Instructions for that is beyond the scope of this manual and can be found on the Internet.

Network

It is possible to install Focus™ locally without being connected to the Internet or a private network, but this defies (at least partially) its purpose as a collaborative web application.
So make sure that your system is connected and that you know the official network address of your system.
Your system should be either reachable directly by IP address (which is acceptable for test installations only) or by an official domain name in the DNS (which is mandatory for globally accessible production systems).
Make sure that no firewall is blocking access to port 8080 of your system.
8080 is the default port and can be changed in config.go (compile-time) or focus.ini (run-time).

Examples:

http://localhost:8080 (test installation without network connection)
http://192.168.1.100:8080
http://www.mysite.org:8080

SSL and Proxying

(needs more detailed Linux engineering knowledge)
For serious production use, you have to either install an SSL proxy server in front of your Focus™ installation or directly configure Focus™ to use an SSL certificate.
Proxying can typically be done with an Apache™ web server or an NGINX web server.
For an SSL certificate we recommend to use the "Let’s Encrypt" approach of https://letsencrypt.org (which issues valid renewable SSL certificates for free).
Here is an example for the Apache™ "/etc/apache2/sites-enabled/default-ssl.conf" configuration file on Linux:

<VirtualHost *:443>
 ServerName www.mysite.org
 DocumentRoot /var/www/html/mysite.org
 SSLEngine on
 SSLCertificateFile /etc/letsencrypt/live/www.mysite.org/fullchain.pem
 SSLCertificateKeyFile /etc/letsencrypt/live/www.mysite.org/privkey.pem
 RewriteEngine On
 ProxyPass / http://localhost:8080/
 ProxyPassReverse / http://localhost:8080/
</VirtualHost>

You can install the "Let’s Encrypt" tooling and obtain a valid SSL certificate with the following commands (example for a Debian Linux installation; you will need a registered functioning domain name before this will work; in this example "www.mysite.org"):

apt-get install certbot python3-certbot-apache
certbot certonly --apache -d www.mysite.org
certbot renew --dry-run
systemctl list-timers

Further installation details are not part of this getting started guide, as they may vary wildly between the installations.
For more details have a look at the generic information on the Internet (e.g. by searching for “apache https proxy”).
To configure Focus™ to directly use an SSL certificate, edit the "focus.ini" file and change the following configuration keys (this is an example):

# web server.
   webaddress = 192.168.0.5
   webport = 8443
   websslactive = true
   websslcert = fullchain.pem
   websslkey = privkey.pem

Please note that if you want use “443” as SSL port, you need to start Focus™ with "root" privileges, which is NOT recommended.
In general we recommend the proxy approach for serious production installations (separation of concerns between application service and security proxy).

Some Examples based on Debian 11

First make sure that "bullseye-backports" is uncommented in /etc/apt/sources.list.
Now install for example all mentioned packages in one go:

apt-get install joe mariadb-server exim4 golang-1.17

Afterwards edit /etc/profiles and add the following line at the end:

export PATH=/lib/go-1.17/bin:${PATH}

Reconfigure Exim4 for Internet delivery:

dpkg-reconfigure exim4-config

Add the autostart file for the compiled executable (joe /etc/rc.local):

##!/bin/sh -e
##
## rc.local
##
## This script is executed at the end of each multiuser runlevel.
## Make sure that the script will "exit 0" on success or any other
## value on error.
##
## In order to enable or disable this script just change the execution
## bits.
##
## By default this script does nothing.

## Focus™ (start the interactive fiction engine)
/root/focus/start.sh

exit 0

Make the file executable and start the associated system service:

chmod +x /etc/rc.local
systemctl start rc-local

Configure an optional MariaDB for UTF8 (joe /etc/mysql/conf.d/utf8.cnf):

[mysqld]
character-set-server=UTF8
[client]
default-character-set=UTF8

MariaDB Tunings for very large installations (optimized for speed):
For serious multiuser production environments, we suggest running the MariaDB server with 4GB main memory and 4 CPU cores.
A minimum diskspace of 64GB is also recommended.

joe /etc/mysql/mariadb.conf.d/50-server.cnf:

max_allowed_packet = 64M
query_cache_size = 64M
innodb_buffer_pool_size = 4GB
innodb_log_file_size = 1GB

joe /etc/mysql/conf.d/mysqldump.cnf:

max_allowed_packet = 64M

Allow for MariaDB connections by all IP addresses.
Choose your own secret password and optionally (for more security) limit access to localhost.

mysql -u root -p
drop user 'root'@'localhost';
create user 'root'@'%' identified by 'password';
grant all privileges on *.* to 'root'@'%';
flush privileges;

Now create a new database for Focus™.
Reconnect to your MariaDB/MySQL instance as root and enter:

create database focus;
use focus;
create user 'melaniebush'@'localhost' identified by 'Test123!';
grant all privileges on focus.* to 'melaniebush'@'localhost';
flush privileges;

Verify if you can successfully connect to your database "focus" as user "melaniebush" with password "Test123!":

mysql -u melaniebush -p focus

Installation and Setup

Download the latest installation bundle from the official Focus™ website:
https://focus.litehouse.dev

Installation bundles are named “focus_YYYY_MM_DD.tar” (with YYYY, MM and DD replaced by year, month and day of the release date).
They are TAR files, which (when untarred) produce a directory called "focus" containing the source files, the compiled executable, the configuration file and a couple of supplementary directories (containing objects, icons and other assets).
Place the downloaded installation bundle into a proper directory on your installation target machine’s file system.
>Unpack the installation bundle from a command line by entering:

cd 
tar -xvf focus_YYYY_MM_DD.tar

The directory will now contain another directory called "focus".
This directory contains all necessary parts of Focus™.

Enter this directory by typing:

cd focus

If you want to better understand what directories and files you find here:
Having a look at the README.txt file in the "focus" directory contains more information.

Now open the Focus™ main configuration file with a text editor:

nano focus.ini

Go through all the configuration items line-by-line and take a closer look at the entries which need to be changed based on your installation environment.
This is usually indicated in the comments of the configuration file.
Make the necessary changes and save the file when you are finished.
Now start the Focus™ service in the background by typing the following:

./start.sh

When starting for the first time, verify the startup output by typing:

tail -f start.out

Watch for any error messages.
A typical problem can be that the web server port 8080 is already in use on your machine.
Type "CTR-C" to stop the "tail" command to continue.

You can stop the Focus™ service again by typing:

ps ax | grep focus
(mark and copy the process id of the running process)
kill [process id]

But if startup of the service was successful, just keep it running.
Now open your browser and connect to your running instance by invoking the database initialization page:

http://localhost:8080/ascabera

The browser will ask you for confirmation to create the tables in your configured database instance.
Confirm and watch the output of your running Focus™ process.
You should only see a couple of error messages for "drop table" statements (which is perfectly normal when running against a newly created empty database).

If you encounter other error messages (for example "create table"), check your configuration in "focus.ini" and make necessary corrections.
If you run this process again, no error messages should show up on the console, as the tables are already in place and can be dropped before being recreated.
If this step completes successfully, you immediately need to perform the following steps:

• Kill the Focus™ process.
• Edit the "focus.ini" again with your text editor.
• Set the configuration parameter "initactive" to "false".
• Restart the Focus™ process.

This will make the above initialization URL inaccessible.
Otherwise anyone who knows the initialization URL can later recreate your database and delete all your data in the process!
Spare you the grieve of such a situation by following the above advice.

Congratulations!

You are ready to use your own installation of Focus™.