fresh

README

Fresh

Fresh is a modern, efficient file server powered by Go.

Deploy (Quick Guide)

1. Build:

go build -o fresh .

1. Create config:

cp fresh.toml /etc/fresh.toml
mkdir -p ./data ./data/tmp

1. (Optional) Enable encryption at rest:

export FRESH_ENCRYPTION_KEY="$(openssl rand -hex 32)"

1. Start server:

./fresh serve --config /etc/fresh.toml

1. Production recommendation:

• Run behind TLS reverse proxy (Caddy/Nginx/Traefik)
• Run as non-root service user
• Enable auth (auth.enabled = true)
• Monitor /healthz, /readyz, /metrics

Use (Quick Guide)

Base URL example: http://localhost:3000

1. Create bucket:

curl -X POST http://localhost:3000/api/images

1. Upload object (multipart):

curl -X POST http://localhost:3000/api/images/objects \
  -F "file=@./photo.jpg" \
  -F "key=photo.jpg"

1. List objects:

curl "http://localhost:3000/api/images/objects?limit=50&prefix=pho"

1. Download object by ID:

curl -L "http://localhost:3000/api/images/objects/1/download" -o out.bin

1. Chunked upload flow:

• POST /api/{bucket}/uploads (init)
• PATCH /api/{bucket}/uploads/{session} (chunks)
• POST /api/{bucket}/uploads/{session}/complete (finalize)

Auth:

• Send Authorization: Bearer <key-or-jwt> when auth is enabled.

Documentation

• API reference: docs/api.md
• E2EE guide: docs/e2ee.md
• Technical notes: docs/README.md
• Operator guide: docs/operators.md

License

This project is licensed under the MIT License.