run.sh: how we manage CLI tasks in imgproxy

  • software development
One bash script to rule them all

The ecosystem we live in

Makefile is not a task runner

No CLI arguments by design

Tip
# Get build arguments
ifeq (build,$(firstword $(MAKECMDGOALS)))
  BUILD_ARGS := $(wordlist 2,$(words $(MAKECMDGOALS)),$(MAKECMDGOALS))
endif

# Declare the build arguments as phony targets to avoid errors
.PHONY: ${BUILD_ARGS}
${BUILD_ARGS}: ; @:

.PHONY: build
build:
  @$(GOBUILD) -v -o ./imgproxy $(BUILD_ARGS) ./cli

No task listing

Syntax that pretends to be shell

.PHONY targets are a must

.PHONY: lint-go
lint-go:
  @echo "Running Go linter..."

.PHONY: lint-clang
ling-clang:
  @echo "Running C linter..."

.PHONY: lint
lint: lint-go lint-clang

No “early exit”

.PHONY: _run-in-docker
_run-in-docker:
ifdef IMGPROXY_IN_BASE_CONTAINER
  @$(MAKE) $(DOCKERCMD)
else
  @docker compose -f "$(MAKEFILE_DIR)/.devcontainer/docker-compose.yml" \
    run --rm -it imgproxy \
    bash -c "make $(DOCKERCMD)"
endif

.PHONY: task _task
task: DOCKERCMD := _task
task: _run-in-docker
_task:
  @echo "Running task..."

What about alternatives?

How standards proliferate

One script to rule them all

Installing the runner

curl -fsSL https://raw.githubusercontent.com/imgproxy/run.sh/main/run -o run && chmod +x run
Tip
./run install-global

Task structure

#!/usr/bin/env bash

# Description for task list
description() { echo "Build the imgproxy binary"; }

# Help message for the task (`run help build`)
help() {
  cat <<EOF
Usage: ./run $TASK_NAME [go-build-args...]

Builds the imgproxy binary. If -o is not passed via go-build-args, the
binary defaults to ./imgproxy.

Example:
  ./run build -o /tmp/imgproxy
EOF
}

# The task itself
main() {
  run::require_tool go "go is required, see https://go.dev/doc/install"
  go build -v -o imgproxy "$@" ./cli
}

List and help

$ run

run.sh — tasks in /Users/gzigzigzeo/go/imgproxy/bin (v0.0.1)

  build-and-run         Build the imgproxy binary, then run it (inside the base container)
  build                 Build the imgproxy binary
  bump-version          Bump the imgproxy version in version.go and CHANGELOG.md

  ...
$ run help build

Usage: ./run build [go-build-args...]

Builds the imgproxy binary. If -o is not passed via go-build-args, the
binary defaults to ./imgproxy.

Example:
  ./run build -o /tmp/imgproxy

Dependencies

main() {
  run::require_tool go "go is required, see https://go.dev/doc/install"
  # Do something with Go
}
main() {
  run::depends_on build test
  # Do something after building and testing
}
main() {
  run::invoke build -o /tmp/imgproxy
  run::invoke launch /tmp/imgproxy
}

Variables and helpers

It's Friday. Are you REALLY sure? (y/N) y

Ok, you're the boss...

┓┏┓┏┓┃
┛┗┛┗┛┃⟍ ○⟋   Friday
┓┏┓┏┓┃  ∕     deploy,
┛┗┛┗┛┃ノ)    good
┓┏┓┏┓┃        luck!
┛┗┛┗┛┃
┓┏┓┏┓┃
┛┗┛┗┛┃
┓┏┓┏┓┃
┃┃┃┃┃┃
┻┻┻┻┻┻

Adding more variables and helpers

BINARY="$PROJECT_ROOT/imgproxy"
require_tool_go() {
  run::require_tool go "go is required, see https://go.dev/doc/install"
}

require_tool_docker() {
  run::require_tool docker "docker is required, see https://docs.docker.com/get-docker/"
}
Important
guard_docker() {
  if [ -n "${IMGPROXY_IN_BASE_CONTAINER:-}" ] || [ -n "${CI:-}" ]; then
    return 0
  fi

  require_tool_docker

  run::msg_ok "switching to docker..."

  local -a tty_flags=(-i)
  if [ -t 0 ] && [ -t 1 ]; then
    tty_flags+=(-t)
  fi

  local rc=0
  docker compose -f "${PROJECT_ROOT}/.devcontainer/docker-compose.yml" run --rm "${tty_flags[@]}" imgproxy \
    bash "./run" "$TASK_NAME" "$@" || rc=$?

  exit "$rc"
}
main() {
  guard_docker
  go test
}

Explaining run.sh to AI agents

## Running tasks: use `./run`

All build, test, lint and run workflows go through the `./run` dispatcher.
Do not call `go build`, `go test`, `golangci-lint`, `gofmt` or `clang-format` directly.

- `./run` lists tasks.
- `./run help <task>` shows a task's usage.
- Tasks live in `bin/<name>.sh`. Shared config is in `.runrc`.
- Extra args pass through to the underlying tool. Example: `./run test -run TestFoo ./processing/...`.

### Tasks for everyday work

| Task | Use it for |
|---|---|
| `build` | Compile to `./imgproxy`. See the note below. |
| `run` / `build-and-run` | Start the server in Docker. Env vars come from `.imgproxyrc`. |
| `test` | Unit tests (gotestsum). Pass `go test` args, e.g. `-run X`, `-asan`. |
| `lint-go` | golangci-lint. Takes its args, e.g. `--timeout 10m0s`. |
| `lint-clang` | clang-format check for `.h`/`.c`/`.cpp`. |
| `lint` | `lint-go` + `lint-clang`. |
| `fmt` | `gofmt -s -w .` |
| `govulncheck` | Vulnerability scan. |
| `lychee` | Link check for README.md and CHANGELOG.md. |
| `clean` | Remove build artifacts. |

**`build` runs on the host and is not Docker-guarded.**
- It only checks that the code compiles.
- The resulting `./imgproxy` binary only works inside the Docker base image. Don't execute it on the host.
- To run the server, use `./run run` or `./run build-and-run`, which re-run themselves in Docker.

### Plans and verification
- A plan must name the `./run` tasks that verify each step. Don't write raw `go` commands.
- Minimum before calling a change done:
  1. `./run test` (add `-run <Name>` to narrow it while iterating, then run the full suite once)
  2. `./run lint`
- Run `./run fmt` after editing Go files.
- If a task can't run (no Docker, no network), say so. Don't claim it passed.

Start your free trial today

Or get imgproxy Pro on Cloud Marketplace

Get in touch

919 North Market Street,
Suite 950
Wilmington, DE
19801

Join newsletter