Getting Started
Last updated
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/pardnchiu/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/pardnchiu/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.