Deployment Options

• Hosted: use https://crafatar.euphoriadevelopment.uk directly.
• Self-hosted: deploy your own Crafatar instance with Docker or Node.js + Redis.

Docker Quick Start (Awaiting Testing 23/02/2026)

Recommended for production deployment.

docker network create crafatar
docker run --net crafatar -d --name redis redis
docker run --net crafatar \
  -v crafatar-images:/home/app/crafatar/images \
  -e REDIS_URL=redis://redis \
  -e EXTERNAL_URL=https://crafatar.example.com \
  -p 3000:3000 \
  ghcr.io/<owner>/<repo>:latest

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

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:

• REDIS_URL=redis://host:6379 (or rediss:// for TLS).
• 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.