Deployment Options

• Hosted: use https://crafatar.euphoriadevelopment.uk directly.
• Self-hosted: deploy with Docker, Docker Compose, Pterodactyl Panel, or Node.js + Redis.

Docker Quick Start

Fast single-host deployment with a dedicated Redis container.

docker network create crafatar
docker run --net crafatar -d --name redis redis:7-alpine
docker run --net crafatar \
  -v crafatar-images:/home/app/crafatar/images \
  -e CACHE_BACKEND=redis \
  -e REDIS_URL=redis://redis:6379 \
  -e BIND=0.0.0.0 \
  -e PORT=3000 \
  -e EXTERNAL_URL=https://crafatar.example.com \
  -p 3000:3000 \
  docker.io/repgraphics/crafatar:latest

Service is then available at http://0.0.0.0:3000 behind your proxy/domain.

Docker Compose (Recommended)

Uses the repo's maintained docker-compose.yml with Redis health checks and persistent volumes.

git clone https://github.com/EuphoriaTheme/crafatar.git
cd crafatar
cp .env.example .env
docker compose up -d
docker compose logs -f crafatar

Windows PowerShell quick start:

Copy-Item .env.example .env
docker compose up -d

The compose stack binds Crafatar to 3000:3000, mounts crafatar-images, and stores Redis data in redis-data.

Pterodactyl Panel Installation

Use the official egg from your repository: pterodactyl egg/egg-crafatar.json.

1. In Pterodactyl Admin, import egg-crafatar.json into a nest.
2. Create a new server with image docker.io/repgraphics/crafatar:latest.
3. Set BIND=0.0.0.0 and configure EXTERNAL_URL to your public domain.
4. For Redis caching, set CACHE_BACKEND=redis and REDIS_URL=redis://host:6379. If you do not run Redis, set CACHE_BACKEND=memory.
5. Start the server and confirm the console reports Server running on http://.

CACHE_BACKEND=redis
REDIS_URL=redis://redis.example.internal:6379
BIND=0.0.0.0
EXTERNAL_URL=https://crafatar.example.com
SOURCE_REPO=EuphoriaTheme/crafatar
SOURCE_REF=master

Manual Setup

• Install Node.js 24 LTS.
• Install and run a Redis server.
• Clone repository and install dependencies.

git clone https://github.com/EuphoriaTheme/crafatar.git
cd crafatar
npm install
cp .env.example .env
npm start

If node-canvas fails to build, install system dependencies from the official node-canvas installation guide.

Required Configuration

Set these in .env:

• CACHE_BACKEND=redis, memory, or none (default is redis in .env.example).
• REDIS_URL=redis://host:6379 (or rediss:// for TLS) when CACHE_BACKEND=redis.
• PORT=3000, BIND=0.0.0.0.
• EXTERNAL_URL=https://crafatar.example.com for canonical public URL in docs/examples.
• CACHE_LOCAL=1200 and CACHE_BROWSER=3600 control freshness and browser cache lifetime.
• RETENTION_ENABLED=true, RETENTION_DAYS=30, RETENTION_INTERVAL_HOURS=24 for cleanup.

Reverse Proxy Example (NGINX)

server {
  listen 443 ssl http2;
  server_name crafatar.example.com;

  location / {
    proxy_pass http://127.0.0.1:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Forwarded-Proto $scheme;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
  }
}

Crafatar reads forwarded headers to build correct external URLs when EXTERNAL_URL is not set.

Validation and Troubleshooting

Basic checks

curl -I "http://127.0.0.1:3000/avatars/069a79f444e94726a5befca90e38aaf5?size=64"
curl -I "http://127.0.0.1:3000/renders/head/069a79f444e94726a5befca90e38aaf5?scale=4"

• Expect 200 and image/png for valid requests.
• Expect 422 for invalid UUID/size/scale/default values.
• If response is slow, verify Redis connectivity and upstream egress to Mojang services.
• If skins do not refresh, lower CACHE_LOCAL or clear image cache/Redis keys.
• If storage fills up, tune retention and monitor inode usage.