Getting Started
This page covers the environment go-image-server needs, the two ways to install it, and your first upload and read.
Prerequisites
| Item | Requirement | Source |
|---|---|---|
| Docker Compose deployment | Docker and Docker Compose | docker-compose.yaml |
| Building from source | Go 1.21+ (the container uses golang:1.22-alpine) |
app/go.mod |
| Image processing | libvips with pkg-config; AVIF output needs libheif / libavif |
apk add in docker-compose.yaml |
| 404 placeholders | app/internal/assets/image/404-light.svg and 404-dark.svg |
configs.Get404SVG() |
The 404 placeholders are not in the repo: the **/image/ rule in .gitignore excludes app/internal/assets/image/, so provide both files before deploying, otherwise failed reads cannot return a placeholder.
Run with Docker Compose
git clone https://github.com/pardnio/go-image-server.git
cd go-image-server
docker compose up -d
| Service | Image | Public port | Notes |
|---|---|---|---|
nginx |
nginx:stable-alpine |
8080 → 80 |
Mounts ./config/nginx, writes logs to ./logs/nginx |
golang |
golang:1.22-alpine |
None | Installs libvips at startup, then runs go build -o main ./cmd/server && ./main |
Image data is mounted from ./image in the project root to storage/image in the container.
Build from Source
git clone https://github.com/pardnio/go-image-server.git
cd go-image-server/app
go build -o main ./cmd/server
./main
Every storage path resolves against os.Getwd(), so run the binary from app/; otherwise storage/image and the placeholders land in the wrong place. The service listens on 8080 by default; override it with PORT (see Configuration).
First Upload and Read
# Upload into storage/image/upload/blog
curl -X POST -F "filepath=@./photo.jpg" http://localhost:8080/upload/blog
# Read it back via the src in the response; WebP by default
curl -o photo.webp "http://localhost:8080/c/img/blog/<filename>"
# Health check
curl http://localhost:8080/check/state
See Upload API for the response format and Image Parameters for read options.