# Enforce private-file authorization for Quarkus

## Summary
Private file access for a Quarkus app on Ample. Verified on Quarkus: a role-to-document access model with negative tests (401, 403) and an authorized private-bucket round-trip (private=ok). Build and start: `./mvnw -q -DskipTests package` producing one uber-jar (quarkus.package.jar.type=uber-jar), then `java -jar` on the jvm-21 template (Temurin JDK 21) with `quarkus.http.port` read from PORT.

## Workflow Steps  
### Build and start  
`./mvnw -q -DskipTests package` producing one uber-jar (quarkus.package.jar.type=uber-jar), then `java -jar` on the jvm-21 template (Temurin JDK 21) with `quarkus.http.port` read from PORT; the server must bind 0.0.0.0 on PORT.

### Create the bucket and pass its credentials  
Create it once with `ample bucket create`, then pass endpoint, region, bucket and keys with --env; use path-style addressing.  
`ample deploy . --name  --public --env S3_ENDPOINT=... --env S3_REGION=... --env S3_BUCKET=... --env S3_ACCESS_KEY_ID=... --env S3_SECRET_ACCESS_KEY=...`

### Authorize before touching storage  
Return 401 for unauthenticated requests and 403 for the wrong role; keep the bucket unpublished and stream objects through the app.

### Verify  
Fetch the live URL and /p/private-document-library on the example; on failure read the build and runtime logs.  
`ample logs  --kind build`

## Prerequisites  
- A Quarkus project (`./mvnw -q -DskipTests package` producing one uber-jar (quarkus.package.jar.type=uber-jar), then `java -jar` on the jvm-21 template (Temurin JDK 21) with `quarkus.http.port` read from PORT)  
- A PostgreSQL driver reading DATABASE_URL at runtime  
- A bucket from `ample bucket create` with credentials passed as encrypted S3_* environment variables  
- An Ample account token with servers:write, databases:read, buckets:read

## Examples  
### Quarkus pattern fixture  
**Description:** Verified private file access on Quarkus.  
**Source Reference:** tests/deploy-canaries/quarkus-patterns

## Success Checks  
- **Description:** App responds on its public URL  
  **Kind:** http_get  
  **Path:** /  
  **Expect:** ample canary quarkus patterns  
- **Description:** Private-document-library check from the example  
  **Kind:** http_get  
  **Path:** /p/private-document-library  
  **Expect:** see the pattern fixture checks

## Limitations  
- Verified on the jvm-21 template at s-1vcpu-2gb; other sizes and Quarkus major versions are not verified.  
- Region, compliance attestations and request-duration limits are unknown and not claimed.  
- Managed PostgreSQL 16 only; extensions, connection limits and backup or restore procedures are not verified.  
- PutObject and GetObject with path-style addressing are verified; other S3 operations are not.

## Cost Estimate  
- **Currency:** USD  
- **Monthly Amount:** 10.0  
- **Basis:** size prices from pricing.toml (loaded by the API) at build revision 1ac5595375130d45290090e82ed0f554ccd45405-dirty  
- **Components:**  
    - **Name:** app server  
      **Size:** s-1vcpu-1gb  
      **Quantity:** 1.0  
      **Monthly Amount:** 5.0  
    - **Name:** managed PostgreSQL database  
      **Size:** s-1vcpu-1gb  
      **Quantity:** 1.0  
      **Monthly Amount:** 5.0  
- **Note:** Always-on monthly price of the tested sizes; apps auto-pause when idle. Buckets are allocation-priced per quota and not included.

## Evidence Summary  
- **Kind:** canary_run  
- **Summary:** Quarkus pattern fixture deployed on Ample (`./mvnw -q -DskipTests package` producing one uber-jar (quarkus.package.jar.type=uber-jar), then `java -jar` on the jvm-21 template (Temurin JDK 21) with `quarkus.http.port` read from PORT); for this guide: a role-to-document access model with negative tests (401, 403) and an authorized private-bucket round-trip (private=ok).  
- **Observed At:** 2026-09-21T00:35:31Z  
- **Implementation Revision:** c6c81daa9272c95c5ce381005ba7347a341e578f-dirty (CLI 0.1.21)  
- **Expires At:** 2027-03-20T00:35:31Z  
- **Scope:**  
  - **Checks:** [/p/private-document-library]  
  - **Template:** jvm-21

## MCP Binding  
- **Registry Reference:** mcp:ample_deploy  
- **Tool Name:** ample_deploy  
- **Schema Hash:** 876465fce906da0c224d62961d3343064108ebe30af80cf1b87094974e948853  
- **Observed At:** 2026-09-21T03:19:59.461917+00:00  
- **Implementation Revision:** 49962bcade4f  
- **Required Scopes:** [servers:write, databases:read, buckets:read]  
- **Binding State:** current

## Unknowns  
- Region availability is unknown until a verified region fact is recorded  
- Compliance attestations are unknown; none are claimed

## Formats  
- **HTML:** https://ample.computer/guides/quarkus/private-file-access  
- **Markdown:** https://ample.computer/guides/quarkus/private-file-access.md  
- **JSON:** https://api.ample.computer/v1/catalog/recipes/page%3Aguides%3Aquarkus%3Aprivate-file-access

## Next Actions  
- **[Browse the catalog index](https://api.ample.com/v1/catalog)**  
- **[Search published recipes by intent, stack and constraints](https://api.ample.com/v1/catalog/search)**  
- **[Prepare a side-effect-free deployment plan for an authorized project](https://api.ample.com/v1/catalog/plan)**  
- **[Read the existing agent authentication setup](https://api.ample.com/mcp/setup)**  
- **[Browse Quarkus](https://api.ample.com/v1/catalog/nodes/stack%3Aframework-quarkus)**  
- **[Browse Connect app to storage](https://api.ample.com/v1/catalog/nodes/intent%3Aconnect-app-to-storage)**  
- **[Browse Private document library](https://api.ample.com/v1/catalog/nodes/pattern%3Aprivate-document-library)**