<p>Evennia releases <aclass="reference external"href="https://hub.docker.com/r/evennia/evennia/">docker images</a> as part of regular commits and releases. This makes running an Evennia-based game in a Docker container easy.</p>
<p>First, install the <codeclass="docutils literal notranslate"><spanclass="pre">docker</span></code> program so you can run the Evennia container. You can get it freely from <aclass="reference external"href="https://www.docker.com/">docker.com</a>. Linux users can likely also get it through their normal package manager.</p>
<p>gets the image based off Evennia’s unstable <codeclass="docutils literal notranslate"><spanclass="pre">develop</span></code> branch.</p>
<p>Next, <codeclass="docutils literal notranslate"><spanclass="pre">cd</span></code> to a place where your game dir is, or where you want to create it. Then run:</p>
<p>This is a normal shell prompt. We are in the <codeclass="docutils literal notranslate"><spanclass="pre">/usr/src/game</span></code> location inside the docker container. If you had anything in the folder you started from, you should see it here (with <codeclass="docutils literal notranslate"><spanclass="pre">ls</span></code>) since we mounted the current directory to <codeclass="docutils literal notranslate"><spanclass="pre">usr/src/game</span></code> (with <codeclass="docutils literal notranslate"><spanclass="pre">-v</span></code> above). You have the <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span></code> command available and can now proceed to create a new game as per the normal <aclass="reference internal"href="Installation.html"><spanclass="doc std std-doc">game setup</span></a> instructions (no virtualenv needed).</p>
<p>You can run Evennia from inside this container if you want to, it’s like you are root in a little
isolated Linux environment. To exit the container and all processes in there, press <codeclass="docutils literal notranslate"><spanclass="pre">Ctrl-D</span></code>. If you
created a new game folder, you will find that it has appeared on-disk.</p>
<div><p>The game folder or any new files that you created from inside the container will appear as owned by <codeclass="docutils literal notranslate"><spanclass="pre">root</span></code>. If you want to edit the files outside of the container you should change the ownership. On Linux/Mac you do this with <codeclass="docutils literal notranslate"><spanclass="pre">sudo</span><spanclass="pre">chown</span><spanclass="pre">myname:myname</span><spanclass="pre">-R</span><spanclass="pre">mygame</span></code>, where you replace <codeclass="docutils literal notranslate"><spanclass="pre">myname</span></code> with your username and <codeclass="docutils literal notranslate"><spanclass="pre">mygame</span></code> with whatever your game folder is named.</p>
<p>Below is an explanation of the <codeclass="docutils literal notranslate"><spanclass="pre">docker</span><spanclass="pre">run</span></code> command we used:</p>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">docker</span><spanclass="pre">run</span><spanclass="pre">...</span><spanclass="pre">evennia/evennia</span></code> tells us that we want to run a new container based on the <codeclass="docutils literal notranslate"><spanclass="pre">evennia/evennia</span></code> docker image. Everything in between are options for this. The <codeclass="docutils literal notranslate"><spanclass="pre">evennia/evennia</span></code> is the name of our <aclass="reference external"href="https://hub.docker.com/r/evennia/evennia/">official docker image on the dockerhub repository</a>. If you didn’t do <codeclass="docutils literal notranslate"><spanclass="pre">docker</span><spanclass="pre">pull</span><spanclass="pre">evennia/evennia</span></code> first, the image will be downloaded when running this, otherwise your already downloaded version will be used. It contains everything needed to run Evennia.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">-it</span></code> has to do with creating an interactive session inside the container we start.</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">--rm</span></code> will make sure to delete the container when it shuts down. This is nice to keep things tidy
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">-p</span><spanclass="pre">4000:4000</span><spanclass="pre">-p</span><spanclass="pre">4001:4001</span><spanclass="pre">-p</span><spanclass="pre">4002:4002</span></code> means that we <em>map</em> ports <codeclass="docutils literal notranslate"><spanclass="pre">4000</span></code>, <codeclass="docutils literal notranslate"><spanclass="pre">4001</span></code> and <codeclass="docutils literal notranslate"><spanclass="pre">4002</span></code> from inside the docker container to same-numbered ports on our host machine. These are ports for telnet, webserver and websockets. This is what allows your Evennia server to be accessed from outside the container (such as by your MUD client)!</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">-v</span><spanclass="pre">$PWD:/usr/src/game</span></code> mounts the current directory (<em>outside</em> the container) to the path <codeclass="docutils literal notranslate"><spanclass="pre">/usr/src/game</span></code><em>inside</em> the container. This means that when you edit that path in the container you will actually be modifying the “real” place on your hard drive. If you didn’t do this, any changes would only exist inside the container and be gone if we create a new one. Note that in linux a shortcut for the current directory is <codeclass="docutils literal notranslate"><spanclass="pre">$PWD</span></code>. If you don’t have this for your OS, you can replace it with the full path to the current on-disk directory (like <codeclass="docutils literal notranslate"><spanclass="pre">C:/Development/evennia/game</span></code> or wherever you want your evennia files to appear).</p></li>
<li><p><codeclass="docutils literal notranslate"><spanclass="pre">--user</span><spanclass="pre">$UID:$GID</span></code> ensures the container’s modifications to <codeclass="docutils literal notranslate"><spanclass="pre">$PWD</span></code> are done with you user and group IDs instead of root’s IDs (root is the user running evennia inside the container). This avoids having stale <codeclass="docutils literal notranslate"><spanclass="pre">.pid</span></code> files in your filesystem between container reboots which you have to force delete with <codeclass="docutils literal notranslate"><spanclass="pre">sudo</span><spanclass="pre">rm</span><spanclass="pre">server/*.pid</span></code> before each boot.</p></li>
<p>If you run the <codeclass="docutils literal notranslate"><spanclass="pre">docker</span></code> command given in the previous section from your game dir you can then easily start Evennia and have a running server without any further fuss.</p>
<p>But apart from ease of install, the primary benefit to running an Evennia-based game in a container is to simplify its deployment into a public production environment. Most cloud-based hosting
or updating your game as simple as building a new container image locally, pushing it to your Docker Hub account, and then pulling from Docker Hub into your AWS/Azure/other docker-enabled hosting account. The container eliminates the need to install Python, set up a virtualenv, or run pip to install dependencies.</p>
<p>For remote or automated deployment you may want to start Evennia immediately as soon as the docker container comes up. If you already have a game folder with a database set up you can also start the docker container and pass commands directly to it. The command you pass will be the main process to run in the container. From your game dir, run for example this command:</p>
<p>This will start Evennia as the foreground process, echoing the log to the terminal. Closing the
terminal will kill the server. Note that you <em>must</em> use a foreground command like <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span><spanclass="pre">start</span><spanclass="pre">-l</span></code>
or <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span><spanclass="pre">ipstart</span></code> to start the server - otherwise the foreground process will finish immediately
and the container go down.</p>
</section>
</section>
<sectionid="create-your-own-game-image">
<h2>Create your own game image<aclass="headerlink"href="#create-your-own-game-image"title="Permalink to this headline">¶</a></h2>
<p>These steps assume that you have created or otherwise obtained a game directory already. First, <codeclass="docutils literal notranslate"><spanclass="pre">cd</span></code> to your game dir and create a new empty text file named <codeclass="docutils literal notranslate"><spanclass="pre">Dockerfile</span></code>. Save the following two lines into it:</p>
<p>These are instructions for building a new docker image. This one is based on the official
<codeclass="docutils literal notranslate"><spanclass="pre">evennia/evennia</span></code> image, but also makes sure to start evennia when it runs (so we don’t need to
<p>(don’t forget the period at the end, it will use the <codeclass="docutils literal notranslate"><spanclass="pre">Dockerfile</span></code> from the current location). Here <codeclass="docutils literal notranslate"><spanclass="pre">mydhaccount</span></code> is the name of your <codeclass="docutils literal notranslate"><spanclass="pre">dockerhub</span></code> account. If you don’t have a dockerhub account you can build the image locally only (name the container whatever you like in that case, like just <codeclass="docutils literal notranslate"><spanclass="pre">mygame</span></code>).</p>
<p>Docker images are stored centrally on your computer. You can see which ones you have available locally with <codeclass="docutils literal notranslate"><spanclass="pre">docker</span><spanclass="pre">images</span></code>. Once built, you have a couple of options to run your game.</p>
<h3>Run container from your game image for development<aclass="headerlink"href="#run-container-from-your-game-image-for-development"title="Permalink to this headline">¶</a></h3>
<p>Evennia will start and you’ll get output in the terminal, perfect for development. You should be
able to connect to the game with your clients normally.</p>
</section>
<sectionid="deploy-game-image-for-production">
<h3>Deploy game image for production<aclass="headerlink"href="#deploy-game-image-for-production"title="Permalink to this headline">¶</a></h3>
<p>Each time you rebuild the docker image as per the above instructions, the latest copy of your game
directory is actually copied inside the image (at <codeclass="docutils literal notranslate"><spanclass="pre">/usr/src/game/</span></code>). If you don’t mount your on-disk
folder there, the internal one will be used. So for deploying evennia on a server, omit the <codeclass="docutils literal notranslate"><spanclass="pre">-v</span></code>
<p>Your game will be downloaded from your docker-hub account and a new container will be built using the image and started on the server! If your server environment forces you to use different ports, you can just map the normal ports differently in the command above.</p>
<p>Above we added the <codeclass="docutils literal notranslate"><spanclass="pre">-d</span></code> option, which starts the container in <em>daemon</em> mode - you won’t see any
return in the console. You can see it running with <codeclass="docutils literal notranslate"><spanclass="pre">docker</span><spanclass="pre">ps</span></code>:</p>
<p>Stop the container. To get it up again you need to use <codeclass="docutils literal notranslate"><spanclass="pre">docker</span><spanclass="pre">run</span></code>, specifying ports etc. A new
container will get a new container id to reference.</p>
</section>
</section>
<sectionid="how-it-works">
<h2>How it Works<aclass="headerlink"href="#how-it-works"title="Permalink to this headline">¶</a></h2>
<p>The <codeclass="docutils literal notranslate"><spanclass="pre">evennia/evennia</span></code> docker image holds the evennia library and all of its dependencies. It also has an <codeclass="docutils literal notranslate"><spanclass="pre">ONBUILD</span></code> directive which is triggered during builds of images derived from it. This <codeclass="docutils literal notranslate"><spanclass="pre">ONBUILD</span></code> directive handles setting up a volume and copying your game directory code into the proper location within the container.</p>
<p>In most cases, the Dockerfile for an Evennia-based game will only need the <codeclass="docutils literal notranslate"><spanclass="pre">FROM</span><spanclass="pre">evennia/evennia:latest</span></code> directive, and optionally a <codeclass="docutils literal notranslate"><spanclass="pre">MAINTAINER</span></code> directive if you plan to publish your image on Docker Hub and would like to provide contact info.</p>
<p>For more information on Dockerfile directives, see the <aclass="reference external"href="https://docs.docker.com/engine/reference/builder/">Dockerfile Reference</a>.</p>
<p>For more information on volumes and Docker containers, see the Docker site’s <aclass="reference external"href="https://docs.docker.com/engine/tutorials/dockervolumes/">Manage data in
containers</a> page.</p>
<sectionid="what-if-i-dont-want-latest">
<h3>What if I Don’t Want “LATEST”?<aclass="headerlink"href="#what-if-i-dont-want-latest"title="Permalink to this headline">¶</a></h3>
<p>A new <codeclass="docutils literal notranslate"><spanclass="pre">evennia/evennia</span></code> image is built automatically whenever there is a new commit to the <codeclass="docutils literal notranslate"><spanclass="pre">main</span></code> branch of Evennia. It is possible to create your own custom evennia base docker image based on any arbitrary commit.</p>
<li><p>Change your working directory to the <codeclass="docutils literal notranslate"><spanclass="pre">evennia</span></code> directory containing <codeclass="docutils literal notranslate"><spanclass="pre">Dockerfile</span></code>. Note that
<codeclass="docutils literal notranslate"><spanclass="pre">Dockerfile</span></code> has changed over time, so if you are going far back in the commit history you might
want to bring a copy of the latest <codeclass="docutils literal notranslate"><spanclass="pre">Dockerfile</span></code> with you and use that instead of whatever version
was used at the time.</p></li>
<li><p>Use the <codeclass="docutils literal notranslate"><spanclass="pre">docker</span><spanclass="pre">build</span></code> command to build the image based off of the currently checked out commit.
The example below assumes your docker account is <strong>mydhaccount</strong>.</p></li>
<p>Note: From this point, you can also use the <codeclass="docutils literal notranslate"><spanclass="pre">docker</span><spanclass="pre">tag</span></code> command to set a specific tag on your image and/or upload it into Docker Hub under your account.
5. At this point, build your game using the same <codeclass="docutils literal notranslate"><spanclass="pre">docker</span><spanclass="pre">build</span></code> command as usual. Change your
working directory to be your game directory and run</p>
<p>The Docker ecosystem includes a tool called <codeclass="docutils literal notranslate"><spanclass="pre">docker-compose</span></code>, which can orchestrate complex multi- container applications, or in our case, store the default port and terminal parameters that we want specified every time we run our container. A sample <codeclass="docutils literal notranslate"><spanclass="pre">docker-compose.yml</span></code> file to run a containerized Evennia game in development might look like this:</p>
<p>With this file in the game directory next to the <codeclass="docutils literal notranslate"><spanclass="pre">Dockerfile</span></code>, starting the container is as simple as</p>
<p>For more information about <codeclass="docutils literal notranslate"><spanclass="pre">docker-compose</span></code>, see <aclass="reference external"href="https://docs.docker.com/compose/gettingstarted/">Getting Started with docker-
<div><p>Note that with this setup you lose the <codeclass="docutils literal notranslate"><spanclass="pre">--user</span><spanclass="pre">$UID</span></code> option. The problem is that the variable <codeclass="docutils literal notranslate"><spanclass="pre">UID</span></code> is not available inside the configuration file <codeclass="docutils literal notranslate"><spanclass="pre">docker-compose.yml</span></code>. A workaround is to hardcode your user and group id. In a terminal run <codeclass="docutils literal notranslate"><spanclass="pre">echo</span> <spanclass="pre">$UID:$GID</span></code> and if for example you get <codeclass="docutils literal notranslate"><spanclass="pre">1000:1000</span></code> you can add to <codeclass="docutils literal notranslate"><spanclass="pre">docker-compose.yml</span></code> a line <codeclass="docutils literal notranslate"><spanclass="pre">user:</span><spanclass="pre">1000:1000</span></code> just below the <codeclass="docutils literal notranslate"><spanclass="pre">image:</span><spanclass="pre">...</span></code> line.</p>
