Skip to content

Latest commit

 

History

History
149 lines (100 loc) · 7.15 KB

README-image.adoc

File metadata and controls

149 lines (100 loc) · 7.15 KB

Container Creation

Table of Contents

This document describes the components needed to create a standard virtual machine or container for the Massive MapTool Server project.

1. Required Components

The resulting image (either a virtual machine or container) will require:

  1. The SSH daemon (tested with openssh-server v7.6p1)

  2. The desired version of MapTool (current is 1.9.2)

    1. Because MapTool doesn’t have a headless mode, it will require a full graphical desktop environment (the Dockerfile shown below arranges this).

    2. Also required will be either:

      1. A remote desktop application, so the GM can connect to the container’s desktop and execute MapTool, or

      2. An X11 server running on the local system, so that MapTool can be executed remotely with the GUI appearing on the local system. This option doesn’t allow the GM to disconnect as it would kill the SSH tunnel and thus the MapTool server.

Optional components include:

  1. pandoc; for converting this document into HTML

  2. net-tools; for monitoring network activity

  3. tcpdump; for packet recording and analysis

  4. ethtool; for controlling characteristics of network cards

  5. nano; for editing text files

2. Building a Docker Container Yourself

Use the following file as the Dockerfile for creating the image.

link:context/Dockerfile[role=include]

To choose a different version of MapTool, put a different version number in the URL in the curl command (or comment out that line and uncomment the one above it that downloads the most recent release).

3. How to Use the Docker Image

3.1. Upload the Image to DockerHub.com

You don’t have to upload the image to Docker Hub, but it simplifies deployment to most cloud services.

3.2. Create an Instance and Run the Container Image

This varies from one cloud service to the next. For example, with AWS:

  1. Create a Virtual Private Cluster and allocate an instance (the free tier allows r2.micro).

  2. Put a minimal Linux image into the instance (Amazon has such images already packaged or you can create a custom one).

  3. Define a task that holds the result of your Dockerfile build as a container.

    1. The container has to export two ports: 22 (SSH) and 51234 (client MapTool port).

    2. Also configure the Security Group so that ports 22 and 51234 are allowed through.

  4. Start the task.

  5. When you view your list of instances, a public IP address will be shown. Give the IP address and the client MapTool port number to your players.

3.3. Connect to the Container

Use SSH to connect to the container and activate X11 forwarding (this allows a shell command to execute MapTool with the GUI coming back to the local system).

  1. Use scp or sftp to upload files to the container, if needed (the campaign file is a good example).

  2. Start an X11 server on the local system.

    1. Linux uses an X11 server as its GUI desktop so there’s nothing to do;

    2. macOS includes the XQuartz utility, just install and run it;

    3. Windows App Store has X410 and VcXsrv is free, just install and run.

  3. Connect to the container using SSH to get a command prompt.

  4. Start MapTool and pass it the campaign file on the command line. The GUI should open on the local system.

  5. Start a server in MapTool. Be sure to turn off UPNP and use the port number (51234) as allocated in the Dockerfile.

3.4. Configure Public Keys to Allow Player to Connect

Upload a .csv file that contains a list of public keys for each valid player.

This process will eventually become web-based.

  1. Execute the activate.sh script and pass it the name of the .csv file.

    1. It will extract the public keys from the file and write them into the player-keys subdirectory, one per player.

    2. It will then combine the public keys together into the authorized_keys file.

  2. Repeat the above steps at any time to regenerate the player keys.

    1. If all you want to do is remove a player key, it may be easier to simply delete the file from player-keys and re-execute activate.sh without passing it a filename.

    2. In this case, it will combine the public keys into the authorized_keys file but won’t have a .csv file to process.

4. Future Additions

Terms:

Player

Someone who connects to the MapTool server using a MapTool client for the purposes of playing in a game session.

GM

Someone who connects to the MapTool server using a MapTool client for the purpose of running the game session, ie., with GM authority.

Manager

Someone who manages the lists of Players and GMs. (The Manager may also be a GM.)

4.1. Add a web-based interface for player key updates

This will be done in stages:

  1. Allow a .csv file to be uploaded via a web interface.

  2. Create a login process so players do it themselves:

    1. Player creates an account and emails his login id to his Manager.

    2. The Manager adds the player name to his "main list" and that game server now shows up when the player logs in.

    3. The Player can now select the game and generate/upload their own key.

4.2. Implement a custom URL scheme

The MapTool code will be modified to support putting a URL on the command line.

The URL will be in the following format:

maptool://{hostname_or_ip:port|registry_alias}/#username=name[?session_password=...]

Players can put that URL on the command line and MapTool will automatically issue the File → Connect to Server…​ menu option. The connection will be immediately be attempted. If session_password is missing, the dialog will open with the information filled in, but the Password field empty.

Future expansion of this concept will allow any fields that appear in the File → Start Server…​ dialog to be specified as URL get parameters:

maptool://hostname_or_ip:port/#username=name?gm_password=...&player_password=...[&use_upnp=true&rptools_net_alias=...&strict_token_ownership=true&...

In this format:

  1. MapTool will bind to the address given (recommended is 0.0.0.0, which is the same as IPADDR_ANY).

  2. The :port will be the port that the server listens on.

  3. The gm_password and player_password fields must be provided, as they are used to distinguish the role of all clients who connect.

  4. All other options on the dialog are converted to normalized strings and become parameters. (Normalized strings have all occurences of [\s\P{punct}]+ replaced with a single underscore, and all text converted to lowercase.)

  5. Values for checkboxes may be true, on, yes, or 1 to mean the checkbox is checked, and false, off, no, or 0 to mean that it is not.

  6. The movement_metric value should be the values in the dropdown list as normalized strings.

At some point, it would be ideal if each of the platforms we support could be taught that the maptool:// URL is tied to our application. That would allow the user to receive such a URL in an email or see it on a web page, and just click it to invoke MapTool and connect.