https://github.com/4O4/mtasa-docker
Unofficial Docker image for Multi Theft Auto: San Andreas game server
https://github.com/4O4/mtasa-docker
docker docker-image lua mta multi-theft-auto
Last synced: 2 months ago
JSON representation
Unofficial Docker image for Multi Theft Auto: San Andreas game server
- Host: GitHub
- URL: https://github.com/4O4/mtasa-docker
- Owner: 4O4
- Created: 2020-01-01T21:11:21.000Z (over 5 years ago)
- Default Branch: master
- Last Pushed: 2024-09-09T14:53:23.000Z (8 months ago)
- Last Synced: 2024-10-26T06:54:06.795Z (7 months ago)
- Topics: docker, docker-image, lua, mta, multi-theft-auto
- Language: Shell
- Homepage: https://hub.docker.com/r/notfound/mtasa-server
- Size: 28.3 KB
- Stars: 16
- Watchers: 4
- Forks: 8
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
- awesome-mta-sa - mtasa-docker - Unofficial Docker image for MTA:SA game server. (Other)
README
# MTA:SA Server Docker image
Unofficial Docker image for Multi Theft Auto: San Andreas game server. Maintained mostly for myself, but also for anyone from the MTA community who find it useful.
## Details
- This image is automatically built and published on Dockerhub as [`notfound/mtasa-server`](https://hub.docker.com/r/notfound/mtasa-server)
- The base image is Debian Testing (slim) which ensures maximum compatibility and official support
- Total image size is oscillating around 100MiB
- **64-bit server only**
- On Windows, only the [**Docker Desktop with WSL 2 backend**](https://docs.docker.com/docker-for-windows/wsl/) is supported, so expect weird issues with different setup (been there, done that, big NOPE from me). On Linux there are no problems at all.
- The tags always reflect the specific version and build number of the MTA server which they contain, i.e. `1.5.9-21437-v1`
> **Note:** the `v4` in this example is the version number of the tag itself because sometimes something might go wrong and an updated release of the same version and build number is needed)
## Features
- Optimized to be easy to use by anyone
- Comes with a simple scripts which automate boring stuff:
- Automatic resources downloader: If you don't have any resources yet, the official MTA resources package is automatically downloaded and extracted for you before the server is started
- Automatic baseconfig provider: If you don't have your own configuration files, all essential ones are automatically brought to you from the official `baseconfig` archive
- Also covers more advanced scenarios that experienced developers and server owners might find handy:
- Automatic creation of admin / developer account in the built-in accounts system - TODO, soon
- Automatic management of server password, with three strategies (policies) available to be used depending on the use case
- Effortless switching between different server configs, i.e. `mtaserver.dev.conf` file for development and `mtaserver.prod.conf` for the live server
- All of that is configurable via [environment variables](#environment-variables)
- Custom native modules can still be installed easily if needed (native modules will be deprecated in MTA 1.6, so they will be around for a while)
- Full access to the server console input and output, even if the server was started in the background (re-attaching to the console works fine, no `screen` or anything like that is involved - it's all docker)
- Simple directory structure on the root level (`/`) inside the image which makes them easier to find and mount
- Ready for fastdl setups (hosting client files over external HTTP servers)
- Fully prepared for running as a non-root user
- For maximum compatibility with older scripts, the legacy native modules are also included in this image:
- Sockets Module - `ml_sockets.so`
- MySQL module - `mta_mysql.so`
If you want to use them, just remember to [add proper entries to your server config](https://wiki.multitheftauto.com/wiki/Server_mtaserver.conf#module).
- It's battle-tested: I'm using this image by myself in 4 different environments and I consider it production-ready :)
> **Note:** The automatic resources downloader and baseconfig provider mentioned above don't interfere with your existing files. If some essential config files are totally missing, then they will be added for you from the `baseconfig` package, But if you already have your own resources and configs then don't worry - **they will NOT be overwritten**.
## More screenshots
Because everyone likes screenshots
- Resources autodownloader in action:
- Directory structure after running the command visible in the screenshot above (before running it, it was three empty folders)
## Environment variables
- `MTA_SERVER_CONFIG_FILE_NAME` - custom name of the config file, useful for switching between configs for different environments i.e. `mtaserver.dev.conf` for development, `mtaserver.prod.conf` for the live server
## Usage
It's recommended to use this image in a Docker Compose setup, because it's much easier to maintain and configure everything with a YAML file instead of passing all of the options via command line.
TODO: More on that will be here soon
## Usage via command line
This is just for reference and basic testing. You should really consider [using a Docker Compose setup as described in this section](#usage).
### Required manual setup
Create an empty directory somewhere on your disk, then navigate to it and create directories named:
- `mta-resources/`
- `data/`
- `resource-cache/`
The commands in the examples below are [bind-mounting](https://docs.docker.com/storage/bind-mounts/) these directories to the container and they must exist or you will get a nasty error.
### See it in action
Run one of [the example commands](#the-commands) in Powershell on Windows, or in bash on Linux.
### What's going to happen?
If you don't have any resources in `mta-resources/` dir, the official default resources will be automatically downloaded and unpacked there when the container is started.
Server config, acl config, banlist and so on will be available in `data/` in your current directory.
### Important notes
This image is prepared for running as non-root user. Use Docker's `--user` option (or equivalent) to pass the uid / gid (of the non-root user on your host-machine) to the container. Look at examples in the next section.
### The commands
From bash:
```
docker run --name mta-server \
-t \ # allocate tty (always required)
-p 22003:22003/udp \ # map ports to host machine
-p 22126:22126/udp \
-p 22005:22005 \
-v $(pwd)/mta-resources:/resources \ # mount mta resources dir
-v $(pwd)/data:/data \ # mount mta data dir (config, acl, banlist, internal DBs etc.)
notfound/mtasa-server:1.5.9-21437-v1 # remember to adjust the tag name
```
From powershell (basically the only difference is `pwd` syntax):
```
docker run --name mta-server \
-t \ # allocate tty (always required)
-p 22003:22003/udp \ # map ports to host machine
-p 22126:22126/udp \
-p 22005:22005 \
-v ${PWD}/mta-resources:/resources \ # mount mta resources dir
-v ${PWD}/data:/data \ # mount mta data dir (config, acl, banlist, internal DBs etc.)
notfound/mtasa-server:1.5.9-21437-v1 # remember to adjust the tag name
```
## More examples
Only relevant `docker run` options are being shown in each example to avoid redundancy. You can combine options from multiple examples to create the setup that suits your needs.
### Local development
#### Minimal setup
```
docker run --name mta-server \
-t \
-p 22003:22003/udp \
-p 22005:22005 \
-v $(pwd)/mta-resources:/resources \
notfound/mtasa-server:1.5.9-21437-v1
```
#### Or with access to /data (mtaserver.conf, acl.xml etc.)
```
docker run --name mta-server \
-t \
-p 22003:22003/udp \
-p 22005:22005 \
-v $(pwd)/mta-resources:/resources \
-v $(pwd)/data:/data \
notfound/mtasa-server:1.5.9-21437-v1
```
### Running as non-root user:
```
docker run --name mta-server \
-u $(id -u):$(id -g) # set uid and gid of current user
-t \ # allocate tty (always required)
notfound/mtasa-server:1.5.9-21437-v1 # remember to adjust the tag name
```
### Running in the background (daemonized):
```
docker run --name mta-server \
-d # detach
-t \ # allocate tty (always required)
notfound/mtasa-server:1.5.9-21437-v1 # remember to adjust the tag name
```
### Expose resource-cache to setup external fastdl server
```
docker run --name mta-server \
-t \ # allocate tty (always required)
-v $(pwd)/resource-cache:/resource-cache \ # mount cache dir, you only need it if you have fastdl server setup
notfound/mtasa-server:1.5.9-21437-v1 # remember to adjust the tag name
```
### Enforce server password on startup
```
docker run --name mta-server \
-e MTA_SERVER_PASSWORD=mypassword
-e MTA_SERVER_PASSWORD_REPLACE_POLICY=always # always update the entry in the active server config with the value of MTA_SERVER_PASSWORD
-t \ # allocate tty (always required)
notfound/mtasa-server:1.5.9-21437-v1 # remember to adjust the tag name
```
### Set server password on startup, but only if it's not already set in the config
```
docker run --name mta-server \
-e MTA_SERVER_PASSWORD=mypassword
-e MTA_SERVER_PASSWORD_REPLACE_POLICY=when-empty # only update the entry in the active server config if it's not already set
-t \ # allocate tty (always required)
notfound/mtasa-server:1.5.9-21437-v1 # remember to adjust the tag name
```
`when-empty` is the default policy, so this can be simplified to just:
```
docker run --name mta-server \
-e MTA_SERVER_PASSWORD=mypassword
-t \ # allocate tty (always required)
notfound/mtasa-server:1.5.9-21437-v1 # remember to adjust the tag name
```
### Automatically clear server password on startup if it's set in the config
```
docker run --name mta-server \
-e MTA_SERVER_PASSWORD_REPLACE_POLICY=unless-empty # only update the entry in the active server config if it has some value
-t \ # allocate tty (always required)
notfound/mtasa-server:1.5.9-21437-v1 # remember to adjust the tag name
```
### Use custom config file
The config file (in this example it is `mtaserver.mycustom.conf`) must be available in container's data directory, so remember to create a local directory on your host machine, put your config in there and mount this directory as `/data` in the container.
If your custom config file is not present in the data directory, it will be automatically created on container startup and populated with the default configuration from baseconfig.
```
docker run --name mta-server \
-e MTA_SERVER_CONFIG_FILE_NAME=mtaserver.mycustom.conf
-t \ # allocate tty (always required)
-v ${PWD}/data:/data \ # mount mta data dir (config, acl, banlist, internal DBs etc.)
notfound/mtasa-server:1.5.9-21437-v1 # remember to adjust the tag name
```
## Building
This image is built automatically and published on Docker Hub when I push tag to this repo.
To build the image manually I use this exact command:
From bash:
```
env MTA_SERVER_VERSION=1.5.9 MTA_SERVER_BUILD_NUMBER=21437 IMAGE_VERSION=1 \
docker build --build-arg MTA_SERVER_VERSION=${MTA_SERVER_VERSION} --build-arg MTA_SERVER_BUILD_NUMBER=${MTA_SERVER_BUILD_NUMBER} -t mtasa-server:${MTA_SERVER_VERSION}-${MTA_SERVER_BUILD_NUMBER}-v${IMAGE_VERSION} .
```
From powershell:
```
$env:MTA_SERVER_VERSION="1.5.9"; $env:MTA_SERVER_BUILD_NUMBER="21437"; $env:IMAGE_VERSION="1";
docker build --build-arg MTA_SERVER_VERSION=$env:MTA_SERVER_VERSION --build-arg MTA_SERVER_BUILD_NUMBER=$env:MTA_SERVER_BUILD_NUMBER -t mtasa-server:$env:MTA_SERVER_VERSION-$env:MTA_SERVER_BUILD_NUMBER-v$env:IMAGE_VERSION .
```