goodoldtos/aranym repository overview

⁠A Docker image for Aranym to run Atari machines on a Docker host

Customized EasyAraMint package (highly recommended package to download for quick start setup!) and more (including Dockerfile) available at:

Docker aranym on GitHub⁠.

Docker hub link: https://hub.docker.com/r/goodoldtos/aranym⁠

A demonstration video is available on You Tube⁠ for a Quick Start.

⁠What is it?

It's a Docker container running Aranym⁠. You connect to Aranym via a X11 VNC client such as TightVNC Viewer⁠. It comes with a FreeMint install with many things such as network, SSH server already setup on Mint.

⁠What do you need?

• An host with Docker/Docker-compose installed. It has been tested on Linux but should also work on Docker desktop for Windows.
• A X11 VNC client, such as TightVNC Viewer⁠, to connect to the container
• Optionally, a SSH client, such as Putty⁠, to open a SSH session to FreeMint

⁠Installation

⁠Copy Aranym data folder on the host side

Please note this section is no longer required as container should automatically download Aranym data. You should go directly to next section (Create docker-compose file).

Aranym data and configuration is expected to be found in /aranym folder in container. This folder shall be mapped to some host folder, e.g. /home/docker/aranym. Make sure docker user has full access to this folder.Expected content is available at aranym_data on goodoldtos.com⁠ or aranym_data on free.fr⁠.

So typically open a terminal to your docker host,, create a folder for sharing data with container and get this archive (first link should be faster):

mkdir -p /some/path
cd /some/path
wget https://vision.goodoldtos.com/download/aranym_data.tar.xz
-or-
wget http://vision.atari.org/download/aranym_data.tar.xz

And then extract the contents:

tar -xvf aranym_data.tar.xz

Then you can delete aranym_data.tar.xz

In the extracted folder, you will find mainly:

I DO recommend you download the customized EasyAraMint package. You can then customize it to your needs but at least you have some default configuration to work with.

⁠Create docker-compose file

Unless you need to customize the Docker image, you should simply adapt the following docker-compose file to your needs:

version: "3.9"
services:
  aranym:
    container_name: aranym
    image: goodoldtos/aranym
    restart: on-failure:1
    ports:
      - 5900:5900
      - 22000:22000
    environment:
      - TZ=Europe/Paris
      - VNC_KEYBOARD=fr
      - ARANYM_RESOLUTION=1680x960x32
      - ARANYM_MODE=JIT
      - ARANYM_SSH=22000
      - ARANYM_FASTRAM=512
      - ARANYM_ID=10   # optional, last digit of IP address, 2 if not present
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun
    volumes:
    - /mnt/xdata/docker_data/bck/aranym/data:/aranym
# Following volumes are optional, make sense if you want to connect to some shared NFS/CIFS folder available on the host
# Available folders created on the container are:
# /mnt/photo
# /mnt/video
# /mnt/music
# /mnt/data
# /mnt/extra
# Examples:
#    - /mnt/nas/photo:/mnt/photo
#    - /mnt/nas/video:/mnt/video
#    - /mnt/nas/documents:/mnt/data

Some explanations:

⁠Exposed ports by Docker host:

    ports:
      - 5900:5900
      - 22000:22000

Here you may need to change the first 5900 or 22000 ports. 5900 is the port number to use for VNC connection; 22000 is the port number to use to connect to FreeMint from a SSH client within the container.

⁠Environment variables:

⁠Docker Network specfic:

    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun

Don't change these; they are required to setup network in container to enable FreeMint to be accessible from your local network.

⁠Shared data between host and container:

    volumes:
    - /mnt/xdata/docker_data/bck/aranym/data:/aranym

You have to change the left part "/mnt/xdata/docker_data/bck/aranym/data" to some folder on your Docker host defined at previous step.

⁠Defaut passwords

Two passwords are required:

• Password to establish X11 VNC session with Debian image running in container
• Password for SSH session to connect to Mint ran by Aranym

They are set to "aranym" (without quotes) by default. For security considerations, you might want to change them:

• To change original VNC password, open a bash session to Docker container and type: x11vnc -storepasswd /aranym/x11vnc.pass Next VNC session must then be open using new password. Original password should be kept in x11vnc.pass.ori to secure any coming back.
• To change SSH password, just open a SSH connection and use Linux command "passwd' to change it.

⁠Usage

Once docker-compose file is customized, you can start the container either via Portainer or by docker-compose (from folder where docker-compose.yml file is located):

docker compose up -d 

Look at Docker logs (docker logs -f aranym), you should see that container is automatically downloading Aranym data (C, D drives and host_fs). If an error occurs: Download aranym_data on free.fr⁠ or aranym_data on goodoldtos.com⁠ and extracted it into docker host folder mapped to /aranym container volume.

Using a VNC client (e.g. TightVNC Viewer⁠), connect to the IP of the host running Docker and port 5900 (if you did not change it in docker-compose file). Use a SSH client such as Putty⁠ to open a SSH session to Mint.

⁠Some remarks

⁠Container exit

This remark is no longer valid as container restart has been fixed

Upon container exit (NOT X11 VNC session exit), typically by initiating a shutdown from Mint, you should delete the container as well or next start will lead to errors on X11 stack. Typically, you have to run the following on Docker host, from docker-compose file folder:

docker compose down

If you have using Portainer, just remove the container from Portainer GUI.

⁠Terminating X11 client session

If you close the X11 client, you can restart it later on and you will find your FreeMint environment in same state as you left it.

⁠MIT License

Copyright (c) 2023 Good Old TOS

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.