prongbang/gocron

By prongbang

•Updated 17 days ago

Image

7.1K

Overview Tags

prongbang/gocron repository overview

⁠ gocron

Gocron⁠ manages cron jobs with a configuration.

gocron web dashboard

⁠Install by Source

go get github.com/prongbang/[email protected]

Using

package main

import (
	"github.com/prongbang/gocron/cmd/gocron/runner"
	_ "time/tzdata"
)

func main() {
	runner.Start()
}

⁠Install by Docker

⁠Configuration with API

docker-compose.yml

services:
  gocron:
    image: prongbang/gocron:1.2.0
    ports:
      - "8000:8000"
    environment:
      - TZ=Asia/Bangkok
      - GOCRON_API=true

⁠Web dashboard

With GOCRON_API=true, open http://localhost:8000⁠ to manage jobs and browse run history. The dashboard is embedded in the binary and the Docker image.

Building from source? Run make build (needs bun⁠) so the dashboard is embedded; a plain go build still works but serves the API only.

⁠Authentication

Off by default. Turn it on with:

    environment:
      - GOCRON_API=true
      - GOCRON_AUTH=true
      - GOCRON_ADMIN_USER=admin          # first admin, created only when no user exists
      - GOCRON_ADMIN_PASSWORD=change-me  # 8-72 characters

Role	Can
`viewer`	See jobs and history
`editor`	Also create and stop jobs
`admin`	Also manage users (`/v1/users`)

The dashboard signs in with a cookie. Scripts get a token (valid 24h) and send it as a Bearer header:

TOKEN=$(curl -s localhost:8000/v1/auth/login -H 'Content-Type: application/json' \
  -d '{"username":"admin","password":"change-me"}' | jq -r .data.token)
curl -H "Authorization: Bearer $TOKEN" localhost:8000/v1/scheduler

Put gocron behind HTTPS (a reverse proxy) when it is reachable from outside your machine.

⁠Create

POST http://localhost:8000/v1/scheduler

Request

{
    "project": "billing",
    "cron": "*/1 * * * *",
    "task": {
        "type": "api",
        "config": {
            "url": "http://localhost/notify",
            "method": "POST",
            "header": {
                "X-API-KEY": "ABC"
            },
            "body": {
                "data": "Hi"
            }
        }
    }
}

Response

{
    "code": "201",
    "message": "Created",
    "data": {
        "job": "83ba2dc9dd5c4326a07dc9eb2d5163b3"
    }
}

⁠Get all

GET http://localhost:8000/v1/scheduler

Response

{
    "code": "200",
    "message": "OK",
    "data": [
        {
            "job": "83ba2dc9dd5c4326a07dc9eb2d5163b3",
            "project": "billing",
            "cron": "*/1 * * * *",
            "task": {
                "type": "api",
                "config": {
                    "url": "http://localhost/notify",
                    "method": "POST",
                    "body": {
                      "data": "Hi"
                    },
                    "header": {
                        "X-API-KEY": "ABC"
                    }
                }
            },
            "running": true,
            "next_run": "2026-09-19T09:41:00+07:00"
        }
    ]
}

⁠Stop

POST http://localhost:8000/v1/scheduler/stop

Request

{
    "job": "83ba2dc9dd5c4326a07dc9eb2d5163b3"
}

Response

{
    "code": "200",
    "message": "OK",
    "data": {
        "job": "83ba2dc9dd5c4326a07dc9eb2d5163b3"
    }
}

⁠History

Every run of an API-created job is recorded and kept for 7 days (not recorded in BuildIn mode).

GET http://localhost:8000/v1/history?project=billing&status=failed&q=timeout&page=1&limit=20

Param	Description
`job`	Only runs of this job id
`project`	Only runs of this project
`status`	`ok` (2xx) or `failed` (anything else)
`q`	Case-insensitive search in job, project, method, url, status and response
`page`	1-based, default `1`
`limit`	1-100, default `20`

Response (newest first; projects lists every project in history, for filters)

{
    "code": "200",
    "message": "OK",
    "data": {
        "items": [
            {
                "job": "83ba2dc9dd5c4326a07dc9eb2d5163b3",
                "project": "billing",
                "cron": "*/1 * * * *",
                "method": "POST",
                "url": "http://localhost/notify",
                "status": 504,
                "response": "gateway timeout",
                "started_at": "2026-09-19T09:49:00.0012+07:00",
                "duration_ms": 60000
            }
        ],
        "total": 1,
        "projects": ["billing", "reports"]
    }
}

⁠Configuration with BuildIn

schedulers:
  - job: "every-24-hours"
    cron: "0 0 * * *"
    task:
      url: "http://localhost/post"
      method: "POST"
      body: >
        {"data": "every-24-hours"}
      header: >
        {"X-Api-Key": "XXX"}

⁠Config from File

Project structure

project
├── configuration
│     └── configuration.yml
└── docker-compose.yml

docker-compose.yml

services:
  gocron:
    image: prongbang/gocron:1.2.0
    environment:
      - TZ=Asia/Bangkok
      - GOCRON_API=true
      - GOCRON_BUILDIN=true
      - GOCRON_SOURCE=file
    volumes:
      - "./configuration.yml:/app/configuration/configuration.yml"

⁠Config from Remote Key/Value Store Example - Encrypted

docker-compose.yml

services:
  gocron:
    image: prongbang/gocron:1.2.0
    environment:
      - TZ=Asia/Bangkok
      - GOCRON_BUILDIN=true
      - GOCRON_SOURCE=remote
      - GOCRON_REMOTE_SECURE=true
      - GOCRON_REMOTE_PROVIDER=http://127.0.0.1:4001
      - GOCRON_REMOTE_ENDPOINT=true
      - GOCRON_REMOTE_PATH=/config/hugo.yml
      - GOCRON_REMOTE_SECRET_KEYRING=/etc/secrets/mykeyring.gpg

⁠Config from Remote Key/Value Store Example - Unencrypted

docker-compose.yml

services:
  gocron:
    image: prongbang/gocron:1.2.0
    environment:
      - TZ=Asia/Bangkok
      - GOCRON_BUILDIN=true
      - GOCRON_SOURCE=remote
      - GOCRON_REMOTE_SECURE=true
      - GOCRON_REMOTE_PROVIDER=http://127.0.0.1:4001
      - GOCRON_REMOTE_ENDPOINT=true
      - GOCRON_REMOTE_PATH=/config/hugo.yml

Tag summary

Recent tags

Content type

Image

Digest

sha256:eb03d7f33…

Size

11 MB

Last updated

17 days ago

docker pull prongbang/gocron