Compare commits

...
2 Commits
Author SHA1 Message Date
sneak 21b875e86c README Getting Started ends with a signed image request (closes #357)
check / check (push) Successful in 1m12s
Getting Started now runs script/bootstrap --cgo before make build, says
that logging in at http://localhost:8080/ needs debug, and ends with a
signed /v1/image/ request for an image on any public HTTPS server. Its
curl exits non-zero when pixa refuses the request.

Model: opus-5-5
2026-11-11 20:58:52 +00:00
clawbot 0de6972c2d Run make devserver from environment variables, not a config file (closes #360)
check / check (push) Canceled after 0s
The target mounted config.dev.yml, which nothing creates, so Docker made
a directory in its place and pixad exited. It now passes a new random
PIXA_SIGNING_KEY each run, printed so the developer can log in, and
PIXA_DEBUG=true so the login form works over plain HTTP. The unused
.gitignore entry for config.dev.yml is removed.

Model: opus-5-5
2026-11-11 21:55:58 +01:00
3 changed files with 45 additions and 16 deletions

No files matched your search

-1
View File
@@ -70,4 +70,3 @@ vendor/
# Local dev configs # Local dev configs
config.yml config.yml
config.yaml config.yaml
config.dev.yml
+7 -4
View File
@@ -79,12 +79,15 @@ docker-versioned:
docker-test: docker-test:
@script/test @script/test
# Run local dev server in Docker # Run local dev server in Docker, with debug on and a new random signing
# key each run. Log in to the page with the key it prints.
devserver: docker-versioned devserver-stop devserver: docker-versioned devserver-stop
@key="$$(head -c 32 /dev/urandom | base64)" && \
docker run -d --name pixad-dev -p 8080:8080 \ docker run -d --name pixad-dev -p 8080:8080 \
-v $(CURDIR)/config.dev.yml:/etc/pixa/config.yml:ro \ -e PIXA_SIGNING_KEY="$$key" -e PIXA_DEBUG=true \
pixa:latest pixa:latest >/dev/null && \
@echo "pixad running at http://localhost:8080" echo "pixad running at http://localhost:8080" && \
echo "signing key: $$key"
# Stop dev server # Stop dev server
devserver-stop: devserver-stop:
+38 -11
View File
@@ -15,9 +15,10 @@ In this document, the upstream host is the server that holds an original image.
## Getting Started ## Getting Started
```bash ```bash
# clone and build # clone, install what compiling needs, and build
git clone https://git.eeqj.de/sneak/pixa.git git clone https://git.eeqj.de/sneak/pixa.git
cd pixa cd pixa
script/bootstrap --cgo
make build make build
# make a config file from the example and put a real signing key in it # make a config file from the example and put a real signing key in it
@@ -26,18 +27,30 @@ openssl rand -base64 32 # prints a new signing key
$EDITOR config.yml # replace the signing_key placeholder with it $EDITOR config.yml # replace the signing_key placeholder with it
./bin/pixad --config config.yml ./bin/pixad --config config.yml
# or build and run the Docker image # or build and run the Docker image with that signing key
make docker make docker
docker run -p 8080:8080 -e PIXA_SIGNING_KEY="$(openssl rand -base64 32)" pixa:latest docker run -p 8080:8080 -e PIXA_SIGNING_KEY='the new signing key' pixa:latest
``` ```
`make build` compiles pixa on your machine into `bin/pixad`. `pixad` is the `script/bootstrap --cgo` installs Go, a C compiler and the image libraries pixa
server program. Compiling needs the libraries `script/bootstrap --cgo` installs needs (see Deployment). `make build` then compiles pixa on your machine into
(see Deployment). `bin/pixad`. `pixad` is the server program.
The signing key is pixa's one required secret. It must be 32 characters or The signing key is pixa's one required secret. It must be 32 characters or
longer. The placeholder in the example file is refused at startup. longer. The placeholder in the example file is refused at startup.
A container takes its settings from environment variables (see Configuration).
Only `PIXA_SIGNING_KEY` is required. Without it, the container exits at startup
and names the variable. Every other setting has a built-in default. A config
file mounted at `/etc/pixa/config.yml` is read when present. An environment
variable wins over the same setting in the file.
pixa's login page is at `http://localhost:8080/`. Logging in there works only
with `debug: true` in `config.yml`, or `-e PIXA_DEBUG=true` for the container.
Otherwise pixa refuses the login with 403, because the page was opened over
plain HTTP. Use `debug` only on your own machine. A pixa that others use serves
its pages over HTTPS through a reverse proxy (see Deployment).
Once pixa runs, it serves images through URLs of this form: Once pixa runs, it serves images through URLs of this form:
``` ```
@@ -60,11 +73,25 @@ The example config allowlists no host. Every image on an allowlisted host is
served to anyone, without a signature, at any size and in any format. So served to anyone, without a signature, at any size and in any format. So
allowlist only hosts you control, where nobody else can put images. allowlist only hosts you control, where nobody else can put images.
A container takes its settings from environment variables (see Configuration). To see pixa serve an image, sign a URL for an image on any public HTTPS server.
Only `PIXA_SIGNING_KEY` is required. Without it, the container exits at startup Run this in a second terminal while pixa runs, with your own signing key and
and names the variable. Every other setting has a built-in default. A config image:
file mounted at `/etc/pixa/config.yml` is read when present. An environment
variable wins over the same setting in the file. ```bash
key='the new signing key'
image_host=cdn.example.com # a public HTTPS server
image_path=/photos/cat.jpg # an image on it
exp=$(($(date +%s) + 3600)) # the URL expires in one hour
sig=$(printf '%s' "$image_host:$image_path::400:300:webp:$exp:85:cover" |
openssl dgst -sha256 -hmac "$key" -binary | base64 | tr '+/' '-_')
curl --fail-with-body -o cat.webp \
"http://localhost:8080/v1/image/$image_host$image_path/400x300.webp?sig=$sig&exp=$exp"
```
`cat.webp` is then the image at 400x300. If pixa refuses the request, curl
reports an error and `cat.webp` holds pixa's error message instead. The image
path must not hold a `%`, a `:` or a query. Signed URLs explains how to sign
those.
## Deployment ## Deployment