Docker Aseprite Headless

Build your own Docker images featuring an Aseprite binary suitable for CLI use cases such as in build scripts or automated workflows like GitHub Actions.

Tip

If you would like to compile Aseprite with a GUI, please look to the official documentation for more information. For use-cases that require a docker-based compilation targeting a Linux host, please take a look at nilsve/docker-aseprite-linux.

Warning

This project only supports building Aseprite v1.3.15+ for Debian Trixie based images.

Quickstart

To build a fresh image using an Aseprite binary built from the main branch of Aseprite's GitHub repository:

# Creates image with tag aseprite:main-headless
docker buildx bake --pull --no-cache

To confirm that the image runs as a container:

docker run --rm -it aseprite:main-headless --help

To perform some Aseprite cli task on some file in the current host directory:

docker run --rm -it -v .:/workspace aseprite:main-headless --batch --layer 'Layer 1' example.aseprite --save-as example.png

To build from some other ref within the Aseprite repository, override the bake variable's default value:

# Creates image with tag aseprite:v1.3.15.5-headless
ASEPRITE_GIT_REF=v1.3.15.5 docker buildx bake --pull --no-cache

Please refer to the docker-bake file for all available bake variables and their default values.

Makefile

A simple Makefile is provided to help ease build invocations:

 —— Docker Aseprite Headless Makefile ———————————————————————————————————————— 
help                           Outputs this help screen.
build                          Build the aseprite image. Pass the parameter "c=" to pass additional options and arguments to docker bake; example: make build c="--no-cache --pull"

You may populate a git-ignored .env file with bake variable values, for use with the make build command. For example:

IMAGES_PREFIX="kidthales/"
ASEPRITE_GIT_REF="v1.3.15"
ASEPRITE_BUILD_TYPE="RelWithDebInfo"

Warning

Ensure that the values assigned in the .env file are wrapped in double quotes. This is a requirement of the underlying docker buildx bake command used to perform image builds.

GitHub Actions

Some example workflows are utilized in this project to help build and push images to the repository owner's GitHub container registry. When using these workflows in your own repository, please ensure that you are familiar with authenticating in a GitHub Actions workflow and the steps laid out for upgrading a workflow that accesses a registry using a personal access token.