wiredwizard/toaststunt repository overview

⁠Basic Usage

You must map port 7777 and also map a shared volume for the database directory. The three noteworthy directories for mapping are as follows:

/home/moo
/etc/letsencrypt/live/
/home/moorepo

The first directory is required as previously stated, that is where the moo database and log files will live. The second directory is where you will put your certificate and key files, should you wish to enable TLS without using the server rebuild option. If you are not using TLS then you can ignore that directory. Lastly the third directory contains the ToastStunt server source code and repository. You will only need to map that directory if you are using the latest tag and have enabled the REBUILD_SERVER variable.

Note: You will need to map to whatever you set as the PORT environmental variable rather than the default 7777. Also, the "---network host" option only works on Linux at the moment, so if you run this container on a Windows or Mac system, you will probably have to use a bridged network and proper connection details may be obscured from moo functions like connection_name and connection_info. This issue might be related to WSL, so other methods may give you normal results.

As a result of this limitation, I recommend running this container on a Linux docker host, using the host network and changing the PORT variable and mapping the database directory.

For Linux

docker run -dt -v ~/myMooDir:/home/moo -e TZ=America/New_York -e PORT=7777 --network host -p 7777:7777 wiredwizard/toaststunt:latest

For Mac

docker run -dt -v ~/myMooDir:/home/moo -e TZ=America/New_York -e PORT=7777 -p 7777:7777 wiredwizard/toaststunt:latest

For Windows

docker run -dt -v d:\myMooDir:/home/moo -e TZ=America/New_York -p 7777:7777 wiredwizard/toaststunt:latest

When the container starts, it copies the packaged database into the database directory if a database is not already present. It will also create the executables and files directories if they are missing. If you wish to run a different database, simply copy the database you wish to use into the shared volume with the name "moo.db". All tags but minimal are packaged with a Toast core. If you have mapped the source directory, then a copy of the source code will be copied to the directory if it is empty.

⁠NOTE:

If you are running this on Linux, I HIGHLY recommend that you create a custom user on your system to run the moo, via the PUID and PGID variables. Just be certain the user has read/write access to your mapped home and source volumes where the moo database and source code lives as well as read access to any other mapped volumes. Running under root is just unnecessary and not advised.

⁠Tags

latest = The very latest ToastStunt server source build. (the only image supporting the REBUILD_SERVER var. If you don't need this, I recommend using the other smaller and targeted images)
2.7.0 = The current ToastStunt 2.7.0 server build
2.7.0-Minimal = The current ToastStunt 2.7.0 server build, packaged with a minimal.db
test = Only used for my develop testing of the images. I do not ever recommend using this.

⁠Emergency Mode

If you find yourself in the unfortunate situation of needing to run the moo in emergency virtual wizard mode, then I feel your pain. Hopefully you do not. However, if you do, you will want to launch your image using the -it flags to the run command. Below is an example on windows, but it applies to all docker hosts.

docker run -it -rm -v d:\myMooDir:/home/moo -e TZ=America/New_York -e EMERGENCY_MODE="true" -p 7777:7777 wiredwizard/toaststunt:latest

This will create a container with an interactive terminal that will load the moo in emergency mode. From this point it will be just like running emergency mode normally.

⁠Using TLS

If you wish to implement TLS connections there are three good methods for doing so:

1. You can map the directory of /etc/letsencrypt/live/ to a local directory. Then place your key and certificate files in this directory, naming your certificate fullchain.pem and your key file privkey.pem. This is the second easiest method.

2. Use the latest tag image and map the /home/moorepo directory to a local directory. Modify the src/include/options.h file within the directory to reference your key and certificate files directly, then add the REBUILD_SERVER environmental variable to your container to trigger a rebuild of the server at startup. This option is the best choice if you would also like to modify any other server options from the build process.

3. Use the TLS_CERT and TLS_KEY variables to specify your certificate files. This is the easiest method.

If you wish to use TLS, you will need to specify the TLS_PORT variable with a value of the port you wish to use.

⁠Using Compose

below is a sample compose file if you wish to use compose to generate your container

version: "3.9"
services:
  toaststunt:
    container_name: toaststunt
    image: wiredwizard/toaststunt:latest
    tty: true
    environment:
      - TZ=UTC
    ports:
      - 7777:7777
    volumes:
      - /your_fullchain.pem:/etc/letsencrypt/live/fullchain.pem:ro
      - /your_privkey.pem:/etc/letsencrypt/live/privkey.pem:ro
      - /your_moo_dir:/home/moo
      - /your_moo_repo_dir:/home/moorepo

⁠Troubleshooting

Make sure that any directories you are using for mapped volumes are indeed read/write for the user that your container runs under. The TLS encryption cert/key share can/should be read only. So if you create a custom moo user on your system and use PUID/PGID to run the container as that user, you need to insure that the directory being mapped is at the very least readable by moo. In the case of the database and source mapped directories I would just make them and their contents owned by your PUID user to keep it simple. If the executing user cannot see read your mapped volumes then the container will behave as though they were never mapped.

⁠Environmental Variables

There are a number of environmental variables you may define to change server behavior. The following are all variable options
TZ = This will determine the local time zone of the server.
PORT = This determines the listening port of the server for normal connections.
PUID = The id of the host system user you would like your container to run under. (You must specify both PUID and PGID to use either variable)
PGID = The id of the host system group you would like your container to run under. (You must specify both PUID and PGID to use either variable)
EMERGENCY_MODE = If this variable is defined with a value of true, the server will start in emergency virtual wizard mode. For this to operate properly, you should pass the -it flags to your docker run command when you run the image.
START_SCRIPT = This should be a file reference containing text that you want to be passed to #0:do_start_script() when the server starts.
START_LINE = This should be a line of text that you want to be passed to #0:do_start_script() when the server starts.
CLEAR_MOVE = If this variable is defined with a value of true, the last_move builtin property on all objects will be cleared.
WAIF_TYPE = By defining this with a value, it will convert waifs from the specified type (check with typeof(waif) in your old MOO)
NO_OUTBOUND = If this variable is defined with a value of true, outbound network connections will be disabled.
IPV4 = If specified, this will restrict IPv4 listeners to the specific address.
IPV6 = If specified, this will restrict IPv6 listeners to the specific address.
FILE_DIR = You may define this as the path to an alternative directory to store files that may be accessed via the fileio builtins.
EXEC_DIR = You may define this as the path to an alternative directory to store executables that may be run by the exec() builtin.
TLS_CERT = This should be a path reference to your certificate file that you wish to use for TLS connections.
TLS_KEY = This should be a path reference to your key file that you wish to use for TLS connections.
TLS_PORT = If you specify a port number here, the server will attempt to listen on this port for TLS connections. You will need to map the specified port in your configuration.
REBUILD_SERVER = if this is defined with a value of true, the container will rebuild the ToastStunt server at startup (NOTE: this only applies to the 'latest' tag). Using this, you may map the '/home/moorepo' directory to a local directory and drop a copy of the latest source code in there. Once you do that, you may edit the options.h file of the server and force a rebuild at startup, should you wish to modify the default server options. If the src directory of the mapped directory is empty when the container starts, it will pull the source code from git, to your mapped directory. If you do not map the repository directory and use this flag, then the latest server source will be pulled at each startup.