Quick Start Guide

Get up and running with Apps Image in just a few minutes. This guide will show you how to use existing images and add a new application to the repository.

Using Pre-built Images

All Apps Image containers are available on Docker Hub and ready to deploy. Let’s start with a simple example.

Deploy Icones (Icon Explorer)

Pull and run the image

The simplest way to get started is to pull and run an existing image:

docker run -d --name icones -p 8080:80 aliuq/icones:latest

This command:

Pulls the aliuq/icones:latest image from Docker Hub
Runs it in detached mode (-d)
Names the container icones
Maps port 8080 on your host to port 80 in the container

Access the application

Open your browser and navigate to:

http://localhost:8080

You should see the Icones icon explorer running!

Stop and remove (optional)

When you’re done testing:

docker stop icones
docker rm icones

For a quick test without naming the container, use:

docker run --rm --name icones -p 8080:80 aliuq/icones:latest

The --rm flag automatically removes the container when it stops.

Using Docker Compose

For production deployments, Docker Compose is recommended:

Create docker-compose.yml

Create a docker-compose.yml file:

name: icones
services:
  icones:
    image: aliuq/icones:latest
    container_name: icones
    restart: unless-stopped
    ports:
      - '8080:80'

Start the service

docker-compose up -d

View logs (optional)

docker-compose logs -f

Adding a New Application

Let’s walk through adding a new application to the Apps Image repository. We’ll use a simple example to demonstrate the process.

Example: Adding WeekToDo

Create the application directory

Clone the repository and create a directory for your application:

git clone https://github.com/aliuq/apps-image.git
cd apps-image
mkdir -p apps/weektodo
cd apps/weektodo

Use apps/ for application images and base/ for base images that other applications might extend.

Create meta.json

Create a meta.json file to define the application metadata and version tracking:

{
  "name": "weektodo",
  "type": "app",
  "title": "WeekToDo | FOSS Minimalist Weekly Planner",
  "slogan": "每周任务管理工具，高效规划待办事项",
  "description": "WeekToDo is a Free and Open Source Minimalist Weekly Planner and To Do list App focused on privacy. Available for Windows, Mac, Linux or online.",
  "license": "GPL-3.0 license",
  "variants": {
    "latest": {
      "version": "2.2.0",
      "sha": "0296d299bd819e5cf31cf993bad9482fd7787981",
      "checkver": {
        "type": "version",
        "repo": "https://github.com/manuelernestog/weektodo",
        "file": "package.json"
      }
    }
  }
}

Key fields:

name - Image name (will be aliuq/weektodo)
type - Either app or base
variants - Different versions or configurations
checkver.type - Version strategy: version, sha, or manual
checkver.repo - Upstream GitHub repository
checkver.file - File to check for version (for type: version)

Create the Dockerfile

Create a Dockerfile with version placeholders:

FROM alpine/git AS base
WORKDIR /app
ARG VERSION=0296d29
RUN git clone https://github.com/manuelernestog/weektodo . && git checkout ${VERSION}

FROM node:16.20.2-alpine3.18 AS builder
WORKDIR /app
COPY --from=base /app .
RUN yarn install --frozen-lockfile --network-timeout 600000
RUN yarn run build

FROM nginx:1.21.3-alpine

WORKDIR /usr/share/nginx/html
COPY --from=builder /app/dist /usr/share/nginx/html

EXPOSE 80

The VERSION argument uses the short SHA by default. During build, {{version}} and {{sha}} placeholders in the Dockerfile are automatically replaced.

Available placeholders:

{{version}} - Full version string (e.g., 1.2.3)
{{major}} - Major version only (e.g., 1)
{{minor}} - Major.minor version (e.g., 1.2)
{{sha}} - Short commit SHA (7 characters)
{{fullSha}} - Full commit SHA (40 characters)

Create README.md (optional but recommended)

Add documentation for users:

# WeekToDo

> A Free and Open Source Minimalist Weekly Planner

## Quick Start

### Using Docker

```bash
docker run -d --name weektodo -p 8080:80 aliuq/weektodo:latest

Visit http://localhost:8080

Using Docker Compose

name: weektodo
services:
  weektodo:
    image: aliuq/weektodo:latest
    container_name: weektodo
    restart: unless-stopped
    ports:
      - '8080:80'

</Step>

<Step title="Test the build locally">
Before committing, test your Dockerfile:

```bash
# Build the image
docker buildx build -f ./Dockerfile -t weektodo:local --load .

# Test run
docker run --rm --name weektodo-test -p 8080:80 weektodo:local

Access http://localhost:8080 to verify it works.

Commit and push

git add apps/weektodo/
git commit -m "add: WeekToDo application"
git push origin main

The GitHub Actions workflow will automatically:

Detect the new application
Build multi-platform images
Push to Docker Hub and other registries

Advanced Example: Application with Pre-build Hook

For complex applications like Next.js apps, you might need to pre-build assets before Docker builds. Here’s an example with ray.so:

Create meta.json

{
  "name": "rayso",
  "type": "app",
  "title": "ray.so",
  "description": "Create code snippets, browse AI prompts, create extension icons and more.",
  "license": "MIT",
  "variants": {
    "latest": {
      "version": "73fac26",
      "sha": "73fac26b0f184b57ebacd37da95721210a49e1dc",
      "checkver": {
        "type": "sha",
        "repo": "raycast/ray-so"
      }
    }
  }
}

Create pre.sh build script

#!/bin/bash

set -euxo pipefail

VERSION="73fac26"

# Clone the repository
mkdir -p app && cd app
git clone --depth=1 https://github.com/raycast/ray-so . && git checkout $VERSION

# Configure Next.js for standalone output
if ! grep -q 'output:' next.config.js; then
  sed -i '/const nextConfig = {/a\  output: "standalone",' next.config.js;
else
  sed -i 's/output: .*/output: "standalone",/' next.config.js;
fi

# Install Bun and Node.js
mise use bun@latest node@lts -g

# Build the application
bun install --no-cache && bun run build

Pre-build scripts are especially useful for multi-platform builds where building on ARM64 is slow. You can build on x86 in the script, then copy artifacts in the Dockerfile.

Create simplified Dockerfile

FROM node:24-alpine AS runner

WORKDIR /app

ENV NODE_ENV=production \
    NEXT_TELEMETRY_DISABLED=1 \
    PORT=3000 \
    HOSTNAME="0.0.0.0"

RUN addgroup --system --gid 1001 nodejs && \
    adduser --system --uid 1001 nextjs && \
    mkdir -p .next && \
    chown -R nextjs:nodejs /app

USER nextjs

# Copy pre-built assets from pre.sh
COPY --chown=nextjs:nodejs ./app/public ./public
COPY --chown=nextjs:nodejs ./app/.next/standalone/apps/rayso/app ./
COPY --chown=nextjs:nodejs ./app/.next/static ./.next/static

EXPOSE 3000

CMD ["node", "server.js"]

Testing Locally with act

You can test GitHub Actions workflows locally before pushing:

Check Version Workflow

# Check single application
act workflow_dispatch -W .github/workflows/check-version.yaml \
  --input debug=true \
  --input context=apps/icones

# Check multiple applications
act workflow_dispatch -W .github/workflows/check-version.yaml \
  --input debug=true \
  --input context=apps/icones,apps/rayso

# Check all applications
act workflow_dispatch -W .github/workflows/check-version.yaml \
  --input debug=true \
  --input context=all

Build Image Workflow

# Dry run: view docker metadata only
act workflow_dispatch -W .github/workflows/build-test.yaml \
  --input debug=true \
  --input context=apps/icones \
  --input build=false \
  --input notify=false

# Full build: includes image building
act workflow_dispatch -W .github/workflows/build-test.yaml \
  --input debug=true \
  --input context=apps/icones

# Build specific variants
act workflow_dispatch -W .github/workflows/build-test.yaml \
  --input debug=true \
  --input context=apps/icones \
  --input variants=latest,dev

Version Checking Strategies

Apps Image supports three version checking strategies:

1. Semantic Version (`type: version`)

Checks a JSON file (usually package.json) in the upstream repository:

"checkver": {
  "type": "version",
  "repo": "https://github.com/manuelernestog/weektodo",
  "file": "package.json"
}

2. Commit SHA (`type: sha`)

Tracks the latest commit SHA from the default branch:

"checkver": {
  "type": "sha",
  "repo": "https://github.com/antfu-collective/icones"
}

3. Manual (`type: manual`)

No automatic checking - you update versions manually:

"checkver": {
  "type": "manual"
}

Next Steps

Explore Available Images

Browse the complete catalog on Docker Hub

Advanced Configuration

Learn about Docker config, tags, and multi-platform builds

GitHub Actions

Deep dive into the automation workflows

Contributing

Contribute to the project on GitHub

Need help? Check out the GitHub repository or open an issue.

Get Started

Core Concepts

Guides

Automation

Examples

Quick Start

Quick Start Guide

Using Pre-built Images

Deploy Icones (Icon Explorer)

Using Docker Compose

Adding a New Application

Example: Adding WeekToDo

Using Docker Compose

Advanced Example: Application with Pre-build Hook

Testing Locally with act

Check Version Workflow

Build Image Workflow

Version Checking Strategies

1. Semantic Version (`type: version`)

2. Commit SHA (`type: sha`)

3. Manual (`type: manual`)

Next Steps

Explore Available Images

Advanced Configuration

GitHub Actions

Contributing

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

Automation

Examples

​Quick Start Guide

​Using Pre-built Images

​Deploy Icones (Icon Explorer)

​Using Docker Compose

​Adding a New Application

​Example: Adding WeekToDo

​Using Docker Compose

​Advanced Example: Application with Pre-build Hook

​Testing Locally with act

​Check Version Workflow

​Build Image Workflow

​Version Checking Strategies

​1. Semantic Version (type: version)

​2. Commit SHA (type: sha)

​3. Manual (type: manual)

​Next Steps

Explore Available Images

Advanced Configuration

GitHub Actions

Contributing

Build docs developers (and LLMs) love

Quick Start Guide

Using Pre-built Images

Deploy Icones (Icon Explorer)

Using Docker Compose

Adding a New Application

Example: Adding WeekToDo

Using Docker Compose

Advanced Example: Application with Pre-build Hook

Testing Locally with act

Check Version Workflow

Build Image Workflow

Version Checking Strategies

1. Semantic Version (`type: version`)

2. Commit SHA (`type: sha`)

3. Manual (`type: manual`)

Next Steps