# 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

```bash
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

```bash
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](/configuration)).

## First Upload and Read

```bash
# 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](/api-reference-upload) for the response format and [Image Parameters](/api-reference-image) for read options.