This repository provides a Docker-based environment to compile Aseprite into a portable Flatpak bundle. It uses flatpak-builder inside a containerized environment for consistency and leverages a robust host-side script to prepare sources reliably.

Requirements

Docker (BuildKit backend enabled, which is default in modern versions)
Make
Git
Curl
Host kernel with fuse module loaded (common on most desktop Linux systems).
Sufficient disk space and RAM for source code and compilation.
CPU with AVX support: The compiled binary requires a CPU supporting the AVX instruction set (generally CPUs from 2011/Sandy Bridge/Bulldozer onwards).

Important

The Docker build process requires elevated privileges (--privileged) to allow flatpak-builder's sandboxing (bubblewrap) to function correctly. The Makefile handles adding this flag automatically. Ensure your environment allows privileged Docker builds.

Quick Start

Clone:

git clone <repository-url>
cd docker-aseprite-linux

Build:
```
make build
```
Run: Find the compiled Flatpak bundle in ./output/aseprite.flatpak. You can install it using:
```
flatpak install ./output/aseprite.flatpak
```

Build Process Explained

The make build command performs the following steps:

Prepare Sources (via ./prepare_sources.sh):
- This script runs on your host machine first to reliably acquire and prepare the source code.
- Clones depot_tools, Skia, and Aseprite source code into the ./src directory if they don't exist. See the script for specific versions.
- Runs Skia's git-sync-deps command locally with automatic retries (default: 3 attempts, configurable via PREPARE_RETRIES) to download Skia's internal build dependencies (like the gn tool) and mitigate failures from network issues or rate limiting.
- Includes an --check-integrity flag for advanced validation and resetting of source repositories (see Advanced Usage).
- This step isolates the often failure-prone network operations and source state management before the main build begins.
Build Docker Image (using Dockerfile):
- Builds a single Docker image (aseprite-flatpak-builder) based on Debian Slim.
- Installs flatpak, flatpak-builder, and the required Freedesktop Platform/SDK (e.g., 23.08).
- Copies the prepared sources from ./src on the host into /sources inside the container. This leverages Docker's layer caching for the source code.
- Copies the Flatpak manifest com.aseprite.Aseprite.yaml.
- Runs flatpak-builder inside the container using the manifest and the copied sources. This compiles Skia and Aseprite within the consistent Flatpak SDK environment.
- Bundles the result into an aseprite.flatpak file inside the container.
- Note: This step runs with --privileged to allow flatpak-builder's sandboxing mechanisms to work.
Extract Flatpak Bundle: Copies the final aseprite.flatpak file from the container's /output directory to ./output on your host machine.

Troubleshooting

Build Failures

Resource Exhaustion: Compiling Skia and Aseprite requires significant RAM and disk space. Ensure your system (and Docker) has adequate resources allocated.
Network Issues / Rate Limiting (during prepare_sources.sh):
- Ensure you have a stable internet connection. Check for proxy issues if applicable.
- The Skia sync step (git-sync-deps) might hit rate limits (HTTP 429 errors) from Google's servers. The script automatically retries (default: 3 total attempts). If it consistently fails, wait a while before trying again, or increase the number of retries via the PREPARE_RETRIES environment variable (e.g., PREPARE_RETRIES=5 make build).
flatpak-builder Errors (during Docker build):
- Manifest Errors: Check com.aseprite.Aseprite.yaml for syntax errors or incorrect paths/commands.
- SDK Issues: Ensure the SDK version specified in the manifest and Dockerfile is available and installs correctly.
- Sandbox/Bubblewrap Errors (e.g., FUSE issues):
  - Verify the docker build command is running with --privileged (handled by the Makefile).
  - Ensure the fuse kernel module is loaded on your host system (lsmod | grep fuse). If not, try sudo modprobe fuse.
  - Check Docker/BuildKit logs for specific bubblewrap (bwrap) errors.
- Compilation Errors: Check the detailed build log output from Docker (during the flatpak-builder step) for C++/CMake/Ninja errors. These could indicate issues with the source code versions, compiler compatibility, or missing dependencies within the Flatpak SDK.

Runtime Errors (After Installing `.flatpak`)

Illegal instruction: This typically means the compiled binary is trying to use CPU instructions not supported by your processor. This build requires a CPU with AVX support.
Missing Portals / File Dialog Issues: Ensure you have the necessary Flatpak portals installed on your host system (e.g., xdg-desktop-portal, xdg-desktop-portal-gtk or -kde, etc.) for features like file choosers to work correctly.
Permission Issues: If Aseprite cannot save files or access expected locations, review the finish-args in com.aseprite.Aseprite.yaml. The current --filesystem=home is broad; more restrictive permissions might require specific portal interactions.

Advanced Usage

The make build command automatically runs ./prepare_sources.sh without any special flags. If you need to control the source preparation step (e.g., force a check integrity and reset), you can run the script manually before running make build.

Running `prepare_sources.sh` Manually

Check Source Integrity & Reset: Runs git fsck, fetches updates, checks out the exact target commit/tag, and resets submodules. Warning: This performs potentially network-intensive operations and modifies local source directories to match the expected state.
```
./prepare_sources.sh --check-integrity
# If successful, proceed with make build
make build
```
Set Sync Retries: Control the number of retries for the Skia git-sync-deps step (default is 2 retries, total 3 attempts).
```
PREPARE_RETRIES=5 ./prepare_sources.sh
make build
```

Passing Options via `make`

Set Sync Retries via make:
```
PREPARE_RETRIES=5 make build
```
Force Source Reset via make: The recommended way to ensure sources are reset and prepared fresh is to run make clean followed by make build.
```
make clean && make build # Clean output, then build (includes fresh source prep)
```

Clean Up

To remove the build output (./output):

make clean

Note: This does not remove the downloaded sources in ./src. To remove those as well, manually delete the ./src directory or run rm -rf ./src.

Architecture Notes

This project uses a hybrid approach combining a robust host-side source preparation script with a containerized Flatpak build process:

Host-Side Source Prep (prepare_sources.sh): Handles the potentially fragile steps of cloning, syncing dependencies (with retries), and ensuring the correct state of source code repositories locally in ./src.
Docker Build (Dockerfile):
- Creates a consistent build environment using Debian and the standard Flatpak SDK.
- Copies the locally prepared sources into the container, leveraging Docker's layer caching.
- Runs flatpak-builder using com.aseprite.Aseprite.yaml to compile Aseprite against the SDK libraries and the copied sources. Requires --privileged for sandboxing.
Flatpak Manifest (com.aseprite.Aseprite.yaml): Defines the application metadata, permissions, and the sequence of build steps (depot_tools setup, Skia compile, Aseprite compile, metadata installation) executed by flatpak-builder.
Makefile: Orchestrates the process: prepare_sources.sh -> docker build --privileged -> extract .flatpak.

This architecture aims for:

Reliability: By handling source fetching/syncing with retries outside the main build.
Consistency: By using the standard Flatpak SDK inside Docker.
Portability: By producing a .flatpak bundle that should run across different Linux distributions.
Maintainability: By consolidating the build logic into a single Dockerfile and Flatpak manifest.

License

MIT License

README.md

Docker Aseprite Flatpak Builder