Skip to content
Impreza HostdocsSearch documentationCtrl KOpen portal

Upload and reuse source versions

DeploymentsImpreza documentationRead as Markdown ↗

Publish a project archive through My Apps or upload a local folder through MCP. Each upload receives its own immutable context_id, SHA256 and size. Select that version when creating an app or rebuilding an existing uploaded-source app.

From the portal

  1. Open My Apps → Source uploads. Select a .tar.gz or .tgz archive and optionally label the version.
  2. Put project files at the archive root, including the Dockerfile or the package.json and package-lock.json needed by your build recipe. Review the archive before uploading; remove credentials, local dependencies and unnecessary files. The portal sends your archive unchanged.
  3. Choose Uploaded archive in the custom-app form, select the source version and configure Dockerfile, Node npm or static npm build settings. Then choose the server, app name, port and domain.
  4. For later builds, expand Source versions on the app card. Reuse the selected archive or choose another uploaded version and confirm the redeploy.

The app identity, domain, host port and build recipe stay fixed. The selected archive shown on the card is the source for the next build. After a failed deployment or rollback, the running release can still use an earlier source; inspect deployment history and recovery.

Before creating an app, you can inspect an uploaded project and save a plan with source identity, findings and build options.

From MCP

  1. With local MCP 0.22.0+, call impreza_upload_context with dir and an optional label. This stores a source version without creating an app.
  2. Call impreza_list_contexts to list your uploads, or pass context_id to inspect one. Metadata includes SHA256, size, availability, retention and whether an app references it.
  3. Create with impreza_deploy_custom, mode: "dockerfile" and context_id, plus normal app/server/build options. Choose exactly one of dir, git_url and context_id. Direct local dir deployment also retains its uploaded source.
  4. Rebuild with impreza_redeploy_deployment, deployment_id and optionally a new retained context_id. Omission reuses the selected retained archive.
  5. After customer confirmation, impreza_delete_context with context_id and confirm: true removes an unused version. An archive referenced by an app cannot be deleted.

Hosted MCP can list, select and remove uploads made through the portal or REST. It cannot read files on your computer. Upload requires deploy scope, metadata requires read scope, and deletion requires manage scope. Account upload management requires a credential without a resource allowlist; resource-confined credentials cannot access these account-level archives.

The local packer excludes common dependencies and VCS folders, .env, .env.* (except example/sample/template files), .npmrc and .pypirc. This is not a secret scanner and does not interpret .gitignore or .dockerignore. Review all remaining content. Runtime secrets belong in the app's environment settings, not in retained source files.

REST contract

Send raw gzip bytes with Content-Type: application/gzip to POST /v1/platform/deployments/custom/contexts?retain=true&label=release-2. Use your normal API authentication. The response contains context_id, sha256, size_bytes, label, retained, in_use, available, state, created_at, expires_at and unused_expires_at. It never returns a storage path or archive contents.

  • GET /v1/platform/deployments/custom/contexts: latest 100 metadata records for your account.
  • GET /v1/platform/deployments/custom/contexts/{context_id}: inspect one version.
  • DELETE /v1/platform/deployments/custom/contexts/{context_id}: remove an unused archive and its metadata.
  • POST /v1/platform/deployments/custom/{deployment_id}/redeploy with {"context_id":"ctx_..."}: select a retained version for an uploaded-source app.

Another account's identifier returns 404. A referenced archive returns 409 on deletion; an expired or missing source returns 410 when selected. Quota exhaustion returns 429. The agent downloads source through an authenticated endpoint restricted to an owned app on that agent, verifies its size and SHA256, and validates extraction before building.

Retention, quotas and older clients

Retained sources remain available while a custom app references them, including queued or failed apps. Otherwise they expire seven days after upload or the last deployment request. The deadline is not reset when an app switches away or is uninstalled: an older unreferenced version can become eligible for cleanup immediately. The expiry sweep removes the file and metadata. Delete unused versions explicitly when you no longer need them.

Defaults are 10 unexpired or referenced uploads and 300 MiB per account, with at most 100 MiB per archive; operators may impose lower limits. Referenced sources count toward the quota. An in-use retained source reports expires_at: null; unused_expires_at is its deadline if it loses all references. The platform stores retained archives privately outside the public webroot.

Omitting retain=true preserves the older temporary, single-use upload behavior with a 24-hour default TTL. Existing expired files cannot be recovered. To redeploy an older uploaded-source app, upload a fresh retained version and supply its context_id; a new app is not required. The existing agent handles this feature, so no additional agent update is needed solely for retained uploads. Other build features still enforce their documented agent requirements.

What a source version guarantees

The identifier fixes the uploaded bytes. It does not freeze mutable base-image tags, dependencies downloaded during build, external data or runtime secrets. A new archive is rebuilt with the app's existing strategy, paths, public build variables, resource limits and persistent volume configuration. Changing that recipe requires a new app. This flow does not replace Compose topology import or provide artifact promotion between environments.

A failed build preserves the previous running release where supported; failure after replacement follows the configured startup and recovery policy. Rollback does not undo database writes or migrations. See deployment safety, Compose import and agent updates.