Setup #

This document shows the different ways that TLE can be set up. Note that some (all?) of this could be out of date so just make sure you check everything twice.

Docker #

Introduction #

Docker documentation can be found at:-

https://docs.docker.com

Docker works with 'containers' which you can think of as lightweight virtual machines. They can be built once, and deployed in many places.

A docker image has been created to allow the Lacuna Expanse Server to be run from linux, in OS-X or in Windows.

By comparison, if you were to set up a Lacuna Expanse Server, you would need to do so either on a Linux server, or a virtual machine running Centos. You would need to install all the packages, including building Perl and loading all the support libraries and CPAN modules. From experience these can take up to 16 hours to do and to resolve any issues.

By comparison you can download the docker image (perhaps 10 to 20 minutes) and run up the server in just a few seconds in Docker.

Install Docker #

Installation on various systems can be found at

https://docs.docker.com/engine/installation/

Please check the requirements. In particular on Windows you need to ensure that your PC supports virtualization technology and that it is enabled in the BIOS.

When installing, make sure that you opt to have Compose installed along with Docker. Alternatively, you can download and install Compose separately. Either way, it's required to run the setup these days.

Building the Containers #

In theory, it should be as simple as docker compose build and then docker compose up to start everything. If this doesn't work you may need to look at the configuration and try to do what it does by hand.

Initializing the database #

You can connect to the running server (see above) with another bash session.

npm run dev:run -- server bash

This will put you in the bin directory.

The first time you run your image there will be no database and so you should run the following scripts

mysql

mysql> source docker.sql
mysql> exit

cd setup
perl init_lacuna.pl
perl generate_captcha.pl

The two perl scripts will take a while to complete (20 minutes?) but once completed your web server should be ready to go.

The database is preserved via a volume mount to the data/ directory.

Adding AI colonies #

The scheduled jobs (run_hourly.sh etc., driven by schedule.ini in the deployment repo) run the AI empires' hourly updates and attacks, but they never add colonies. The first hourly run after init_lacuna.pl founds each AI empire with a single home world, and that is all it gets until an admin adds more with the faction's add_colonies.pl.

This is deliberately a manual job rather than a scheduled one. Each run permanently adds AI planets, and some factions (Saben in particular) attack players and destroy planets from every colony they hold, so add them when you want more AI presence. Once a colony exists, the hourly updates pick it up automatically.

# Saben / Trelvestian / Diablotin: one colony in the first zone that doesn't have one yet
docker exec -w /home/lacuna/server/bin server perl saben/add_colonies.pl --addone
docker exec -w /home/lacuna/server/bin server perl trelvestian/add_colonies.pl --addone
docker exec -w /home/lacuna/server/bin server perl diablotin/add_colonies.pl --addone

# DeLambert: add N trading-post colonies to the zones with the fewest DeLamberti per player colony
docker exec -w /home/lacuna/server/bin server perl delambert/add_colonies.pl --add=5

• Without --addone, the Saben/Trelvestian/Diablotin scripts add a colony to every zone that doesn't have one yet (except neutral zones). Start with --addone and repeat until you like the density.
• trelvestian/add_colonies.pl --test adds nothing and just prints a message. --tournament is for tournament setups only.
• delambert/add_colonies.pl:
  • --add=N gives each colony a random level from 5 to 30.
  • --each_level adds exactly five colonies, one each at levels 5, 10, 15, 20 and 25.
  • DeLambert only settles zones that already have player colonies, so run it once players have spread out.
• Never run delambert/add_colonies.pl --respawn on a live server. It deletes the DeLambert empire and the AI scratch pads for every faction.
• Each faction only settles certain bodies, e.g. Trelvestian needs unowned planets in orbits 5-6 of size 50-75 (see viable_colonies in lib/Lacuna/AI/<Faction>.pm). The script logs "Could not find a colony to occupy" for any zone with no suitable body.
• Despite their names, jackpot/add_colonies.pl and cult/add_colonies.pl add no colonies. They only found the empire if it doesn't exist yet, which the hourly updates already do. Never run cult/add_colonies.pl --respawn on a live server either: it deletes and recreates the Cult empire.
• Keep the script's output: it names every body it colonised, which you'll need if you ever want to undo one.

Making code changes to the TLE application #

The container running the web application is mapping the directories 'lib','bin','etc' and 'var' from the host. This means that you can make changes to those files using your normal host environment/editors etc. You can also use git commands to change branches, commit etc. in your host. There should be no need to edit files from within your docker container (unless something is going wrong).

However, as normal, if you change your code you will need to restart your web server (that should still be running in your session where you did the docker compose up).

(It is a common mistake to change your code, and forget to restart your server and wonder why your changes are not working!)

If you do need to make changes in your container (for example to do SQL queries) then you can use the same npm run dev:run -- server bash script to open another session or as a one-liner: npm run dev:run -- server <your command here>.

Running the test suite #

The tests in t/ are integration tests: each one drives the game through the JSON-RPC API over HTTP and reads/writes the database directly. They must run INSIDE the server container, talking to that same container's server - not any deployed server, and not from the host.

1. Bring the stack up:

docker compose up -d

2. Wait for the server to answer:

curl -s http://localhost:3050/starman_ping        # -> pong

3. Run the tests with the helper script (the container's working directory is .../bin, so pass -w to run from the server root):

npm run dev:run -- server ./run_tests.sh                # default set
npm run dev:run -- server ./run_tests.sh t/010_Empire.t # a single file

Notes #

• The suite is slow: t/TestHelper.pm sleeps 2 seconds after every RPC call and test setup builds a whole colony. t/long_running/ is excluded from the default run; pass it explicitly if you want it.
• The suite needs MySQL, memcached and beanstalkd up - they are all part of the compose stack, so docker compose up -d covers it.
• An old ./data volume with a database schema older than the code is fixed automatically: bin/start_lacuna.sh (what the server container runs) applies any pending migrations on every boot before serving traffic. See "Schema migrations" in CLAUDE.md.

On the "Bare Metal" #

Step 0: initial requirements. #

These instructions assume that you are setting up a server on (for example) linode.com (a basic 48GB, Linode 2048 is just fine).

If you are not on this environment then you will need to tear apart the scripts and build it yourself.

Create a CentOS 6.5 disk Image using the defaults.

Then boot your linode and SSH into the system as root.

First thing you should do is create a user account, then remove root login via SSH. This blocks one main security hole.

# Create a user account
[root@myserver /]# useradd icydee
[root@myserver /]# passwd icydee
Changing password for user icydee.
New password:
Retype new password:
passwd: all authentication tokens updated successfully.

Remove SSH root login.

[root@myserver /]# vi /etc/ssh/sshd_config

# Make sure the following line is uncommented.
PermitRootLogin no

# While you are at it, prevent timeouts
ClientAliveInterval 30
ClientAliveCountMax 4

# Now exit and restart SSH
[root@myserver /]# /etc/init.d/sshd restart

Install a few repos.

yum install git mysql mysql-devel cpan

Create a directory for the repos and get them

[root@myserver /]# cd /
[root@myserver /]# mkdir data
[root@myserver /]# cd data
[root@myserver data]# git clone https://github.com/plainblack/Lacuna-Server-Open.git

At this point you may need to set up the following, and include it in your bash profile (it was found to be needed in order to run memcache in certain circumstances)

[root@myserver /]# export LD_LIBRARY_PATH=/data/apps/lib

Step 1: Prereqs #

First install all the prerequisites. This works on a ContOS/ RHEL environment.

cd bin/setup/server
./download.sh
./build.sh
cd ..
./install-pm.sh

If not, then you'll need to tear apart those scripts and do what they do.

At some point in this process, /data/apps/bin should be appended to your path and put in the bash profile. You may need to log out and back in make this work correctly.

All of the above will take quite a while, if you suspect a bug, pull the scripts apart and run them manually one by one looking for errors.

Often, the error is that the script is trying to download a version which is no longer supported. Check the web sites for the closest version to use.

Step 2: Start Storage #

You need to start up your MySQL server, memcached, and beanstalk.

Memcached is as easy as:

memcached -d -u nobody -m 512

For a private server, 512 may be overkill, -m 64, the default, is likely sufficient.

For beanstalk, see the info further down. At this point, only the installation/setup is required, the scheduler is not.

MySQL needs one extra bit of configuration. In /etc/my.cnf, find the section labelled "[mysqld]" and add the following line:

log_bin_trust_function_creators = 1

Starting MySQL will depend on the system and how you installed it.

# Make sure MySQL service starts on boot
[root@myserver /]# chkconfig --levels 235 mysqld on

# Start it
[root@myserver /]# service mysqld start

Step 3: Config Files #

You'll need to create lacuna.conf, nginx.conf, and log4perl.conf in your Lacuna-Server/etc folder. Templates exist in the etc directory.

Things you must change in lacuna.conf:

"db" settings to match an account in mysql

Usually it's best to set up a username 'lacuna' in mysql that only has access to the 'lacuna' database. (see below)

"map_size" defines the size, a size of -500 to 500 is good enough to test with

Most other things can stay with their default values.

Things to change in log4perl.conf:

Most things in here can be kept as they are, until you start to need more debugging options.

Things to change in nginx.conf:

"server_name" should be changed from 'myserver.com' to the domain of your server

Most other things in there can be kept as they are.

Step 4: Initialize Database #

Log into mysql:

mysql -uroot -pyourrootpassword

And create a database:

create database lacuna;
grant all privileges on lacuna.* to lacuna@localhost identified by 'somepassword';
flush privileges;
exit;

cd bin/setup
perl init_lacuna.pl
perl generate_captcha.pl

Step 5: Start The Server #

You will need an index.html, this does not come in the code, the best way to get it is to take it from somewhere like

http://pt.lacunaexpanse.com/index.html

and copy it into the var/www/public directory.

(Note: when the frontend was switched to being built with vite, this became unnecessary as the build includes an index.html file which includes hashed asset filenames to bust an end user's cache seamlessly)

To start the lacuna server just type:

cd bin
./start_nginx.sh        # will start nginx as a daemon
./startdev.sh           # will run the dev server, all output will come to the console

Now in another terminal you can start issuing commands to the server.

Step 6: Missions (optional) #

If you want to be able to do anything with missions, you'll need to check out the Lacuna-Mission repository into /data/Lacuna-Mission

Apache #

If you are going to use apache instead of nginx on a local server, the first rule is: this is not the standard deployment on the lacuna servers. So there will be a certain amount of "this is not really supported." However, I've been running this for a while and it seems to work.

These instructions do not replace setup_a_server.txt in its entirety, but only the parts dealing with nginx.

I'm using the apache that comes with the OS, so there's no "start_apache.sh" - use your OS method of starting services. On most systems, you can usually do "/etc/init.d/apache start" or something similar, but there are ways to get it to start automatically on reboot, check your distribution's documentation.

It's the configuration that is the most challenging.

So, I have all of the repositories linked in /data, partly because the perl server requires it. But I expand LSO a little bit

### create the directories
mkdir /data
cd /data
mkdir Lacuna-Server
cd Lacuna-Server

### link in the contents
ln -s /path/to/git/repo/Lacuna-Server-Open/* .

### expand the etc directory
mv etc etc.link
mkdir etc
mv etc.link/* etc
rm etc.link

### now you can go into etc to create your lacuna.conf, etc.

cd etc
cp lacuna.conf.template lacuna.conf
cp log4perl.conf.template log4perl.conf

### edit these new files, they won't show up in your git repository

Do the same thing for Lacuna-Web-Client, etc., except that you can get away without expanding subdirs:

cd /data
ln -s /path/to/git/repo/Lacuna-Web-Client
ln -s /path/to/git/repo/Lacuna-Assets
ln -s /path/to/git/repo/Lacuna-Mission

Then continue with the above server setup until we get to configuring and starting nginx. Here we configure apache. You need to check how your distribution sets up apache. For example, in your httpd.conf may be a line like this:

Include /etc/apache2/vhosts.d/*.conf

That will load any conf file in that vhosts.d directory. This will allow you to create a file, say "lacuna.conf" in that directory that has the following:

<VirtualHost *:80>
    ServerName my.lacunaexpanse.com
    DocumentRoot /data/Lacuna-Web-Client/
    ServerRoot /data/Lacuna-Web-Client/

    <Directory "/data/Lacuna-Web-Client/">
        Options Indexes MultiViews FollowSymLinks
        Require all granted
    </Directory>

    <Directory "/data/Lacuna-Assets">
        Options Indexes MultiViews FollowSymlinks
        Require all granted
    </Directory>

    <Directory "/data/captcha">
        Options Indexes MultiViews FollowSymlinks
        Require all granted
    </Directory>

    <Directory "/home/lacuna/server/var/www/public">
        Options Indexes MultiViews FollowSymlinks
        Require all granted
    </Directory>


    alias /captcha "/data/captcha"
    alias /assets  "/data/Lacuna-Assets"

    ProxyPassMatch ^/([a-z][^.]*)$ http://localhost:5000/$1
    ProxyPreserveHost On
    RemoteIPHeader X-Real-IP

    <IfModule mpm_peruser_module>
        ServerEnvironment apache apache
    </IfModule>
</VirtualHost>

The only thing missing at this point is the index.html that you need. According to the above configuration, that will be found in /data/Lacuna-Web_client/index.html - that will require you to copy it from us1 and change it slightly. (Unnecessary since modern day web client builds. There should already be an index.html file once you have it building)

Restart apache. Once you have the dev server running, you should be able to connect. Recommended is to add something like this to your /etc/hosts:

127.0.0.1  my.lacunaexpanse.com

That way you can put "http://my.lacunaexpanse.com" in your browser and connect to this site, even if you're also using apache to serve other domains.

Beanstalk #

When using beanstalk, the following needs to be done.

Install the following CPAN modules:

• Beanstalk::Client
• App::Daemon

To install beanstalk:

cd /home/lacuna/server/
mkdir third_party
cd third_party
git clone git://github.com/kr/beanstalkd.git
cd beanstalkd
make
make install

add the following in lacuna.conf

    "beanstalk" : {
        "debug" :         0,
        "server" :        "localhost",
        "ttr" :           120,
        "max_timeouts" :  10,
        "max_reserves" :  10
    },

To start beanstalk and to detach

beanstalkd >/tmp/beanstalk 2>/tmp/beanstalk < /dev/null & disown

To run the scheduler

cd /home/lacuna/server/bin
perl schedule_daemon.pl