ulivargas/classroomio

Fork 0

Files

T

Rotimi Best a98d6a35fa docs: selfhostin improvements

2026-03-11 10:53:03 +01:00

5.1 KiB

Raw Blame History

Publishing ClassroomIO Docker Images to Docker Hub

This guide explains how to publish the ClassroomIO API and Dashboard Docker images to Docker Hub.

Prerequisites

Docker Hub Account: Create an account at https://hub.docker.com if you don't have one
Docker Installed: Make sure Docker is installed and running on your machine
Docker Hub Access Token: Create a personal access token at https://hub.docker.com/settings/security

Method 1: Manual Publishing (Local)

docker login
# Enter your Docker Hub username and password/token when prompted

Step 2: Build and Push Images

Use the provided script to build and push both images:

# Default (uses 'classroomio' as username and 'latest' as version)
./docker/docker-push.sh

# Custom username
DOCKERHUB_USERNAME=your-username ./docker/docker-push.sh

# Specific version
VERSION=v0.1.0 ./docker/docker-push.sh

# Both custom username and version
DOCKERHUB_USERNAME=classroomio VERSION=v0.1.0 ./docker/docker-push.sh

Step 3: Verify Images

Check your Docker Hub repository at:

Method 2: GitHub Actions (Automated)

Setup (One-time)

Add Docker Hub Secrets to GitHub:
- Go to your GitHub repository → Settings → Secrets and variables → Actions
- Add two secrets:
  - DOCKERHUB_USERNAME: Your Docker Hub username
  - DOCKERHUB_TOKEN: Your Docker Hub access token
Push the workflow file (already created at .github/workflows/docker-publish.yml)

Publishing via GitHub Actions

The workflow will automatically publish images when:

Push to main/master branch: Creates a latest tag
Create a version tag: Creates versioned tags
Manual trigger: Use the Actions tab in GitHub

Create a version tag and push:

git tag v0.1.0
git push origin v0.1.0

Manual trigger from GitHub:

Go to Actions tab in your repository
Select "Publish Docker Images" workflow
Click "Run workflow"
Enter optional version tag (or leave default 'latest')

Method 3: Individual Image Building

Build API Image

docker build -f docker/Dockerfile.api -t classroomio/api:latest .
docker push classroomio/api:latest

Build Dashboard Image

docker build -f docker/Dockerfile.dashboard -t classroomio/dashboard:latest .
docker push classroomio/dashboard:latest

Using Published Images

Pull Images

docker pull classroomio/api:latest
docker pull classroomio/dashboard:latest

Deploy with Compose

For self-hosting with Docker Compose, see SELF_HOST.md. The setup uses a single root .env file and docker/docker-compose.yaml.

Versioning Strategy

Recommended Tags:

latest: Most recent stable build
v0.1.0: Specific semantic version
v1.0: Minor version
v1: Major version
main: Latest main branch build
dev: Development builds

Example: Publishing a new version

# Build with multiple tags
docker build -f docker/Dockerfile.api \
  -t classroomio/api:latest \
  -t classroomio/api:v1.2.0 \
  -t classroomio/api:v1.2 \
  -t classroomio/api:v1 \
  .

# Push all tags
docker push classroomio/api:latest
docker push classroomio/api:v1.2.0
docker push classroomio/api:v1.2
docker push classroomio/api:v1

Image Sizes and Build Times

API Image: ~400-600 MB (Node.js Alpine + dependencies)
Dashboard Image: ~600-800 MB (Node.js Alpine + SvelteKit build)
Build Time: 5-10 minutes per image (depending on your machine)

Multi-Architecture Support

The GitHub Actions workflow builds for both linux/amd64 and linux/arm64 platforms, making the images compatible with:

x86_64 servers
ARM-based servers (like AWS Graviton)
Apple Silicon Macs (M1/M2/M3)

Troubleshooting

"unauthorized: authentication required"

Run docker login again
Check your Docker Hub token hasn't expired

"denied: requested access to the resource is denied"

Make sure you're pushing to your own username
Repository might need to be created first on Docker Hub

Build failures

Check Dockerfile syntax
Ensure all build arguments are provided
Check available disk space: docker system df

Clean up old images

# Remove dangling images
docker image prune

# Remove all unused images
docker image prune -a

Security Best Practices

Never commit secrets to the repository
Use Docker Hub access tokens instead of passwords
Enable 2FA on your Docker Hub account
Scan images for vulnerabilities:
```
docker scan classroomio/api:latest
```
Use specific version tags in production, not latest

Support

For issues with publishing, please check:

Docker Hub status: https://status.docker.com
GitHub Actions logs in your repository
Docker daemon logs: docker info

5.1 KiB Raw Blame History