Guide

Castmill is a comprehensive digital signage platform. This guide introduces the core concepts and points you to the detailed documentation for each area.

System Architecture

Castmill follows a hierarchical model: Networks contain Organizations, which contain all your content and devices. See Architecture for a detailed breakdown.

Network (domain-based isolation)
└── Organization (workspace)
    ├── Users & Teams (access control)
    ├── Medias (images, videos)
    ├── Playlists (content sequences)
    ├── Layouts (multi-zone arrangements)
    ├── Channels (weekly schedules)
    └── Devices (physical screens)

Core Concepts

Concept	Description	Learn More
Networks	Isolated environments tied to domains — all data stays within a network	Networks
Organizations	Workspaces where teams collaborate, with plan-based quotas	Organizations
Users & Teams	Role-based access (admin, member, viewer) with team-level permissions	Users & Teams
Authentication	Passwordless login using passkeys (WebAuthn)	Authentication

Content Workflow

The typical workflow for getting content onto a screen:

Upload media — Add images and videos to your media library
Create a playlist — Arrange widgets (media, text, web pages) in sequence
Design a layout (optional) — Split the screen into zones, each with its own playlist
Schedule on a channel — Place playlists on a weekly calendar
Assign to a device — Connect the channel to one or more display screens

Detailed Guides

Content & Media — Uploading and managing media files
Playlists — Creating and editing content sequences
Layouts — Multi-zone screen designs
Channels — Weekly scheduling with drag-and-drop
Devices — Registering and managing displays

Dashboard

The Dashboard is the web-based management interface. Key features include:

Sidebar navigation with organization selector and addon support
Table and tree views for all resource types
Tag system for organizing content across the platform — Tags
Usage monitoring with visual quota indicators — Usage & Quotas
User settings including passkey management and language selection — Settings

Widgets

Widgets are the building blocks of playlists. Each widget type defines how a specific kind of content renders — images, videos, text tickers, web pages, and more.

Castmill includes built-in widgets and supports custom widgets that can be developed independently. See the Widgets documentation for the full reference.

Extending Castmill

Castmill's addon system lets you extend the platform with new features. Addons are Elixir packages that register server-side routes and client-side UI components. See the Addons guide for implementation details.

Running a Local S3 Server

For development without AWS, you can use MinIO as a local S3-compatible server:

mkdir -p ~/minio/data

docker run \
   -p 9000:9000 \
   -p 9001:9001 \
   --user $(id -u):$(id -g) \
   --name minio1 \
   -e "MINIO_ROOT_USER=ROOTUSER" \
   -e "MINIO_ROOT_PASSWORD=CHANGEME123" \
   -v ~/minio/data:/data \
   quay.io/minio/minio server /data --console-address ":9001"

Access the MinIO console at http://localhost:9001 (credentials: ROOTUSER / CHANGEME123). Create a bucket, then set: AWS_ACCESS_KEY_ID=ROOTUSER, AWS_SECRET_ACCESS_KEY=CHANGEME123, AWS_S3_BUCKET=<your-bucket-name>, and AWS_REGION=us-east-1.

For the MinIO endpoint (http://localhost:9000), update the ExAws S3 endpoint settings in the Castmill server configuration.

See Self-Hosting for full storage configuration details.

System Architecture​

Core Concepts​

Content Workflow​

Detailed Guides​

Dashboard​

Widgets​

Extending Castmill​

Running a Local S3 Server​