gocron-ui

README

gocron-ui: A Web UI for gocron

A lightweight, real-time web interface for monitoring and controlling gocron scheduled jobs.

If you want to chat, you can find us on Slack at

Installation

go get github.com/go-co-op/gocron-ui

Quick Start

package main

import (
    "log"
    "net/http"
    "time"

    "github.com/go-co-op/gocron/v2"
    "github.com/go-co-op/gocron-ui/server"
)

func main() {
    // create a scheduler
    scheduler, err := gocron.NewScheduler()
    if err != nil {
        log.Fatal(err)
    }

    // add a job to the scheduler
    _, err = scheduler.NewJob(
        gocron.DurationJob(10*time.Second),
        gocron.NewTask(func() {
            log.Println("Job executed")
        }),
        gocron.WithName("example-job"),
        gocron.WithTags("important"),
    )
    if err != nil {
        log.Fatal(err)
    }

    // start the scheduler
    scheduler.Start()

    // start the web UI server
    srv := server.NewServer(scheduler, 8080)
    // srv := server.NewServer(scheduler, 8080, server.WithTitle("My Custom Scheduler")) // with custom title if you want to customize the title of the UI (optional)
    log.Println("GoCron UI available at http://localhost:8080")
    log.Fatal(http.ListenAndServe(":8080", srv.Router))
}

Open your browser to http://localhost:8080 to view the dashboard.

Features

• Real-time Monitoring - WebSocket-based live job status updates
• Job Control - Trigger jobs manually or remove them from the scheduler
• Schedule Preview - View upcoming executions for each job
• Tagging System - Organize and filter jobs by tags
• Configurable Title - Customize the UI header and page title to match your needs
• Embedded UI - Static files compiled into binary, zero external dependencies
• Portable - Single self-contained binary deployment

API Reference

REST Endpoints

Method	Endpoint	Description
GET	/api/config	Get server configuration
GET	/api/jobs	List all jobs
GET	/api/jobs/{id}	Get job details
POST	/api/jobs/{id}/run	Execute job immediately
DELETE	/api/jobs/{id}	Remove job from scheduler
POST	/api/scheduler/start	Start the scheduler
POST	/api/scheduler/stop	Stop the scheduler

WebSocket

Connect to ws://localhost:8080/ws for real-time job updates.

Message Format:

{
  "type": "jobs",
  "data": [
    {
      "id": "uuid",
      "name": "job-name",
      "tags": ["tag1", "tag2"],
      "nextRun": "2025-10-07T15:30:00Z",
      "lastRun": "2025-10-07T15:29:50Z",
      "nextRuns": ["...", "..."],
      "schedule": "Every 10 seconds",
      "scheduleDetail": "Duration: 10s"
    }
  ]
}

Examples

Comprehensive Example

A full-featured example demonstrating 14 different job types is available in the examples directory:

cd examples/getting_started
go run main.go

Demonstrates:

• Interval-based jobs (duration, random intervals)
• Cron expression scheduling
• Daily and weekly jobs
• Parameterized jobs with custom arguments
• Context-aware jobs
• Singleton mode (prevent overlapping executions)
• Limited run jobs
• Event listeners (before/after job runs)
• One-time scheduled jobs
• Batch processing patterns
• Health check monitoring

Visit http://localhost:8080 to see the UI in action.

Basic Auth

See the basic_auth example for how to secure GoCron-UI using a simple basic auth middleware with the credentials being sourced via environment variables.

Deployment

Binary Distribution

# Build
go build -o gocron-ui

# Run
./gocron-ui

The binary is self-contained and requires no external files or dependencies.

Docker

docker build -t gocron-ui .
docker run -p 8080:8080 gocron-ui

See Dockerfile for details.

Configuration

The server accepts the following configuration through the NewServer function:

server.NewServer(scheduler gocron.Scheduler, port int, opts ...ServerOption) *Server

Parameters:

• scheduler - Your configured gocron scheduler instance
• port - HTTP port to listen on
• opts - Optional configuration settings (available configuration Options are listed here)

Custom Title

You can customize the UI title using the WithTitle option:

srv := server.NewServer(scheduler, 8080, server.WithTitle("My Custom Scheduler"))

This will update both the browser tab title and the header title in the UI. When using a custom title, the UI automatically displays a subtle "powered by gocron-ui" attribution below the title.

Command-line Example

You can also make the title configurable via command-line flags:

func main() {
    port := flag.Int("port", 8080, "Port to run the server on")
    title := flag.String("title", "GoCron UI", "Custom title for the UI")
    flag.Parse()

    scheduler, _ := gocron.NewScheduler()
    // ... add jobs ...
    scheduler.Start()

    srv := server.NewServer(scheduler, *port, server.WithTitle(*title))
    log.Fatal(http.ListenAndServe(fmt.Sprintf(":%d", *port), srv.Router))
}

Then run with:

go run main.go -port 8080 -title "My Awesome Scheduler"

Important Notes

Job Creation Limitation

GoCron UI is a monitoring and control interface for jobs defined in your Go code. Jobs cannot be created from the UI because they require compiled Go functions to execute. The UI provides:

• ✅ Real-time monitoring
• ✅ Manual job triggering
• ✅ Job deletion
• ✅ Schedule viewing
• ❌ Job creation (must be done in code)

Production Considerations

• Authentication: This package does not include authentication. Implement your own auth middleware if deploying publicly.
• CORS: Default CORS settings allow all origins. Restrict this in production environments.
• Error Handling: Implement proper error logging and monitoring for production use.

Maintainers

• @iyashjayesh | Maintainer

Star History