Shopboard

A tactile project board for the shop

Keep jobs, notes, links, and reference photos where everyone can see them—without accounts, workspaces, or setup screens.

Shopboard opens directly to the board and stays out of the way. It is designed for a mechanic shop, workshop, garage, or any shared space that needs a clear view of what is waiting.

Highlights

• Whiteboard and chalkboard themes with handwritten marker and chalk styling.
• Quick project capture with optional notes and multiple links.
• Tactile interactions including hand-drawn checkboxes, title underlines, and a board-aware erase animation.
• Safe removal with a persistent undo action and empty spaces that the next project can fill.
• Duplicate detection that warns before adding a project with the same name.
• Pinned reference photos under a draggable desktop magnet, with a dedicated mobile photo view.
• Responsive layout that fills the available board without desktop scrolling.
• No login and no cloud service required.

Dark chalkboard theme	Focused mobile layout

Quick start

Run the published container

The current main image is published for both linux/amd64 and linux/arm64:

docker run -d --name shopboard -p 3000:3000 -v shopboard-data:/app/data --restart unless-stopped ghcr.io/ydkmlt84/shopboard:main

Open http://localhost:3000.

The shopboard-data volume keeps projects, settings, undo history, and photos across container updates and restarts.

Build with Docker Compose

git clone https://github.com/ydkmlt84/shopboard.git
cd shopboard
docker compose up --build -d

Compose stores project metadata in the shopboard-data volume and bind-mounts uploaded images to ./data/uploads, making the image files easy to access from the host.

Using the board

1. Select Add item at the lower-left corner and enter a project name.
2. Add notes or links when the job needs more context.
3. Select an item title to edit its details.
4. Check an item when it is complete, or erase it when it leaves the board.
5. Use the hamburger menu to rename, filter, export, undo, enter fullscreen, or reset the board.
6. Select or drag the desktop magnet to pin photos. On mobile, use the separate Photos tab.

The board title, projects, completion state, links, photo metadata, magnet position, and last removed item persist automatically.

Photo storage

JPEG, PNG, WebP, and GIF images are supported. Each upload can contain up to six photos, each stored image can be up to 10 MB, and a board can hold up to 24 photos.

Still images larger than 5 MB are resized in the browser to a maximum edge of 2560 pixels and converted to WebP before upload. Animated GIFs are kept as-is.

To choose a different host folder when using Compose, copy .env.example to .env and update:

SHOPBOARD_UPLOADS_PATH=./data/uploads

Windows absolute paths should use forward slashes:

SHOPBOARD_UPLOADS_PATH=C:/Users/your-name/Pictures/shopboard

Run for development

Requires Node.js 20 or newer and Yarn through Corepack:

corepack enable
yarn install
yarn dev

The development server runs at http://localhost:3000 and automatically restarts when application files change.

Data and security

Shopboard intentionally uses JSON files instead of a database. That keeps a single trusted board simple, portable, and easy to back up. SQLite is the likely next storage layer if simultaneous writes or external integrations become necessary.

There is no authentication. Shopboard is intended for a trusted local network. If it is exposed outside that network, place it behind an authenticated reverse proxy or private VPN.

Container tags

Tag	Purpose
main	Most recent successful build from the main branch
latest	Current default image
sha-<commit>	Immutable build for a specific commit
1.2.0, 1.2	Release images created from a tag such as v1.2.0

Images are published to GitHub Container Registry and Docker Hub by the container workflow.

Maintainer publishing setup

Before the first workflow run:

1. Create a Docker Hub repository named shopboard.
2. Create a Docker Hub personal access token with read and write permission.
3. In GitHub, open Settings → Secrets and variables → Actions.
4. Add DOCKERHUB_USERNAME as a repository variable.
5. Add DOCKERHUB_TOKEN as a repository secret.

GHCR uses the workflow's built-in GITHUB_TOKEN. New GHCR packages are private by default, so change the package visibility after its first publish if the image should be available publicly.

The workflow publishes on pushes to main, semantic version tags matching v*.*.*, and manual runs.

HTTP API

The browser uses a small JSON API that is ready to be extended for external integrations:

• GET /api/items
• POST /api/items
• DELETE /api/items
• GET /api/items/undo
• POST /api/items/undo
• PATCH /api/items/:id
• DELETE /api/items/:id
• GET /api/photos
• POST /api/photos
• GET /api/photos/:id/file
• DELETE /api/photos/:id
• GET /api/settings
• PATCH /api/settings

Projects accept a links array containing up to eight HTTP or HTTPS URLs. For compatibility, the API also accepts the original single link field or a comma/newline-separated links string.

License

Shopboard is available under the MIT License.