benbou/black-playground repository overview

⁠Black Playground — Self-Hosted Docker Edition

A lightweight, self-hosted web playground for the Black⁠ Python code formatter, derived from José Padilla's MIT-licensed Black Playground⁠.

This version is designed to run entirely inside a single Docker container. Formatting is performed locally using the Black package installed in the image; no Vercel, AWS formatter API, database, Node.js, or persistent storage is required.

⁠Features

• Side-by-side Python input and formatted output
• Black version displayed directly in the UI
• Configurable line length and target Python versions
• Support for Black options including:
  • --fast
  • --skip-source-first-line
  • --skip-string-normalization
  • --skip-magic-trailing-comma
  • .pyi mode
  • preview mode
  • unstable mode
• Shareable/bookmarkable playground states
• Single exposed HTTP port
• Non-root container
• Built-in health check
• No volumes or persistent storage required

⁠Quick Start

docker run -d \
  --name black-playground \
  --restart unless-stopped \
  -p 3000:3000 \
  benbou/black-playground:latest

Then open:

http://YOUR-SERVER-IP:3000

To use another host port, for example 3088:

docker run -d \
  --name black-playground \
  --restart unless-stopped \
  -p 3088:3000 \
  benbou/black-playground:latest

⁠Docker Compose

services:
  black-playground:
    image: benbou/black-playground:latest
    container_name: black-playground
    restart: unless-stopped
    ports:
      - "3000:3000"

Start it with:

docker compose up -d

⁠Tags

Successful builds are published with several tags:

latest
black-X.Y.Z
sha-<git-sha>

⁠latest

Recommended for normal installations, including Unraid.

docker pull benbou/black-playground:latest

⁠black-X.Y.Z

Pins the container to a particular Black release.

For example:

docker pull benbou/black-playground:black-26.5.1

⁠sha-*

Identifies the exact source revision used to produce an image.

⁠Automatic Updates

The image automatically tracks the latest stable Black release published to PyPI.

The build system checks for new Black releases every six hours. A rebuild is also performed when the application source changes and periodically to incorporate updated base-image packages.

Before an image is published, the freshly built container is started and smoke-tested. The tests verify:

• container health
• the installed Black version
• the web interface
• the formatter API
• an actual Python formatting request

The image is pushed to Docker Hub only after those checks succeed.

Because latest is updated when a successful build is published, systems such as Unraid can detect when a newer container image is available.

⁠Unraid

Typical configuration:

Repository:       benbou/black-playground:latest
Network Type:     Bridge
Container Port:   3000
Host Port:        3000 (or any available port)
Volumes:          None

Then browse to:

http://UNRAID-IP:3000

⁠Architecture

Browser
   │
   │ :3000
   ▼
Gunicorn + Flask
   ├── HTML / CSS / JavaScript frontend
   └── Local Black formatter API
            │
            ▼
        Black (PyPI)

Everything required to format Python code runs inside the container.

⁠Health Check

The container includes a built-in Docker health check.

You can inspect it with:

docker inspect \
  --format='{{json .State.Health}}' \
  black-playground

The application also exposes:

GET /api/health
GET /api/version

⁠Security

The application runs as a non-root user inside the container.

It is primarily intended for local/LAN use. If exposing it publicly, place it behind an appropriate reverse proxy with authentication and rate limiting.

⁠Upstream Projects

This image is based on:

• Black: https://github.com/psf/black⁠
• Black Playground: https://github.com/jpadilla/black-playground⁠
• Original hosted playground: https://black.vercel.app⁠

The original Black Playground project is copyright José Padilla and distributed under the MIT License. The original license is retained in this project.

This Docker image is an independent self-hosted adaptation and is not an official Black or Black Playground distribution.