UPVALE / GUIDES

Applications

Deploy a container image or build a Git repository, then configure runtime settings and routes.

On this page

An application runs a container image in a project environment. Use an existing image or build one from a connected GitHub, GitLab, or Bitbucket Cloud repository. Create its configuration, deploy a revision, and use its detail page to inspect replicas, logs, and routes.

Find your way around

Open an application from its project environment or the Applications list. The header shows its status, image, version, and internal hostname. The hostname is for other services on its private network; adding a public route is a separate choice.

TabWhat you use it for
ApplicationSource, image, replicas, placement, resources, storage, environment variables, health checks, routes, and deployment automation.
DeploymentsGit builds and build logs, running containers, deployment status, revision comparisons, rollback, and a terminal for a running replica.
BackupsBack up all named volumes, set a schedule, and restore to a new application.
LogsContainer output, with replica selection and search.
MonitoringHistorical resource metrics, including individual replicas.
TraefikThe generated routing file, or a manually maintained routing configuration.
SecurityRequest limits, IP rules, and HTTP security headers.
AdvancedProcess overrides, published ports, restart policy, and Linux isolation settings.

Your role determines which tabs and actions are available. The Save changes bar stays at the bottom while you edit. Save before deploying; use Discard when you want to abandon a form change.

Before you start

Have a project environment assigned to a cluster with at least one node. Choose an image that its nodes can pull or a Git repository containing a Dockerfile. Your role needs Manage workloads to create or edit an application and Manage deployments to deploy or operate it. Environment variables and managed file content require Manage secrets. Logs require View logs.

For a web application, know the port on which the container serves requests. For a private image, have the appropriate registry connection available in Upvale. For a custom hostname, have access to its DNS records and the public ingress address for your cluster.

Create an application

  1. Open Workloads, then open your project.
  2. Choose the intended environment in the environment selector beside the project name.
  3. Select Add Service → Application. The New application page keeps the project selected.
  4. Under Basics, enter a Name.
  5. Under Source, choose Container image and enter Repository, Tag, and Registry. For Git repository, follow Build from a repository below.
  6. Under Runtime, enter the Container port for a web service, choose Replicas, and set Placement. The initial replica count is 1 and placement is Automatic — any available node.
  7. Configure any resources, storage, health check, environment variables, and routes needed by the image, using the sections below.
  8. Select Create application, or Create and build application for Git. Upvale opens the application's detail page.
  9. For a container image, select Deploy as revision v1 in the header. A Git application starts its first build automatically. Follow progress in Deployments, then check Last successful deployment and Running replicas.

Creating an image-based application saves its configuration; deployment is a separate action. Creating a Git application queues a build and deploys the resulting image when the build succeeds.

Clone configuration

Select Clone configuration to new application in an application's header to open the normal creation form with its settings filled in. The Configuration cloned from banner identifies the source. Enter a new Name, review the destination and settings, then select Create application. Opening the form creates nothing and leaves the source unchanged.

Cloned volumes start empty. Host folder mounts, public routes, and published ports are not copied. Git clones are saved without starting a build or deployment, and Deploy on push starts disabled. Build and deploy explicitly after creation. Use the project's Compose workflow to copy Compose-managed application configuration.

A simple first application

For a first deployment, use a public web-server image:

FieldValue
Namehello-web
Repositorynginx
Tagstable
Registrypublic / anonymous
Container port80
Replicas1
PlacementAutomatic — any available node

Leave the other sections unchanged. Add a route with your own hostname, or use sslip.io if the cluster offers it. Create the application, deploy it, then use Open route. For your own image, replace the repository, tag, and port with those used by your application.

Build from a repository

An infrastructure manager connects GitHub, GitLab, or Bitbucket Cloud under Repositories → New connection. Applications in the same Upvale organization can reuse the connection. Follow the Repositories guide to connect an account.

Choose Git repository as the application source, then set:

SettingValue
Repository connectionA saved connection from Repositories. Its provider determines the repositories available.
Repository and BranchThe repository and branch to build. The repository's default branch is selected initially.
Build nodeAn online node in the application's cluster that will run the Docker build.
DockerfileA path relative to the build context; initially Dockerfile.
Build contextA directory relative to the repository root; initially .. Find this under Advanced build settings.
Timeout (seconds)Build timeout, initially 900, from 60 to 3600.
Deploy on pushBuild and deploy new commits pushed to the selected branch.

Upvale stores build images privately and generates their repository names and tags. To use an external registry, enable Advanced build settings → Use my own registry, then choose a Build registry with push access and enter the full Image repository, such as ghcr.io/acme/web.

For GitLab and Bitbucket Cloud, enabling Deploy on push also needs permission to create repository webhooks. Leave it off to build manually when that permission is unavailable.

Configure the container port and other runtime settings as usual, then select Create and build application. Upvale checks out the selected commit, builds the Dockerfile, pushes the image, and deploys it by digest. Build settings use Dockerfiles; there is no separate build command field.

Open Deployments → Builds to see the commit and build status, cancel a queued or running build, or select Rebuild and deploy to build the current branch again. The Build operation and Deployment links show each stage. Logs opens saved build output; viewing build output requires Manage secrets and Manage workloads. Build history requires View monitoring.

To change the repository, branch, or build settings, edit Application → Source, select Save source, then build and deploy. Save or discard other application edits before changing the source. Switching to Container image asks for the image and registry to use; saving switches the source without deploying. Previous build history remains available.

Remove unused connections in Repositories. A connection still used by an application must first be changed or detached from that application's source.

Choose the image and registry

Enter the repository and tag separately. Do not append :tag to Repository.

Image locationRegistry selectionRepository exampleTag example
Public Docker Hub imagepublic / anonymousnginxlatest
Public image on another registrypublic / anonymousghcr.io/acme/webv1.0.0
Image using a saved connection whose host is ghcr.ioThat saved connectionacme/webv1.0.0

The saved registry supplies its host, so omit that host from Repository when using the connection. Replace the example namespace, repository, and tag with an image you can access. A deployment resolves the tag to the image digest it will run.

Runtime and placement

SettingWhat it changes
Container portThe port your process listens on inside its container. Routes use this unless they specify a different target port. Setting it does not publish a host port.
ReplicasHow many copies of the application should run, from 1 to 100. Each has its own container and resource limits.
Automatic — any available nodeDocker chooses an eligible node.
Worker nodes onlyRun only on Swarm workers.
Manager nodes onlyRun only on Swarm managers.
Specific nodeKeep every replica on the selected node. Use this when a workload needs that node's local data.
Custom constraints (preserved)Keeps an existing placement rule that the simple selector cannot represent.

The application must listen on an address reachable from outside its container, usually 0.0.0.0, rather than only 127.0.0.1. Increasing replicas does not copy local files or make a stateful application safe for multiple writers.

Set environment variables

With Manage secrets, open Environment variables and select Add variable. Enter the variable name, then choose the value source:

  • value stores the value entered in the row.
  • secret lets you select an existing secret available to the project.

You can switch from Rows to Editor to enter one NAME=value per line. For example:

LOG_LEVEL=info
API_TOKEN=[API_TOKEN]

[API_TOKEN] refers to a stored secret named API_TOKEN; create that secret before referencing it. The brackets have special meaning in the editor. If a name exists at both project and organization scope, use [API_TOKEN@project] or [API_TOKEN@organization].

Secret references are resolved at deployment time. Save and deploy a configuration change before expecting it in the running application.

Add persistent storage

In Storage, select Volume mount and enter:

  • Logical volume name: the name of this application's volume.
  • Container path: the absolute path where the image writes its data, such as /app/data when that is the path required by your image.
  • Read-only: enable this only when the application should not write to the mount.

Volume names are scoped to the service. Local volumes belong to a particular node: the same logical name on another node does not contain the same data. For persistent local data, choose the intended node under Runtime → Placement → Specific node. Changing placement does not migrate the data.

Multiple replicas may write to a mounted volume concurrently. Use multiple writers only when the application and storage support them. Applications with writable persistent mounts can have an interruption during deployment while the previous writer is stopped before its replacement starts.

File mount is available with Manage secrets. Enter File name, an absolute Container file path including the filename, and File content. This produces a read-only configuration file, with a maximum of 500 KB. Use environment secrets for credentials; do not put passwords or private keys in file content.

Set resources and a health check

Resources provides vCore limit, Memory limit (MB), Shared memory (MB), and optional process limits. Fractional vCore limits such as 0.5 are accepted. Shared memory is private to each container and counts toward its memory limit; leaving it blank uses Docker's 64 MB default.

In Health check, enter a Command and configure Interval (seconds), Timeout (seconds), Retries, and Start period (seconds). The command runs through CMD-SHELL inside the container, so the image must contain the command and any tools it uses.

Resource limits

OptionMeaning
vCore limitCPU available to each replica. 0.5 is half a CPU core. Blank leaves this limit unset.
Memory limit (MB)Memory available to each replica. A process can be killed if it exceeds this limit.
Shared memory (MB)Size of the container's /dev/shm, used by some databases, browsers, and worker libraries.
Add ulimitAdds a Linux process limit. Soft is the active limit and Hard is its ceiling. -1 means unlimited.

The ulimit selector supports these limits:

LimitWhat it controls
nofileOpen file descriptors.
nprocProcesses.
memlockLocked memory, in bytes.
stackProcess stack size, in bytes.
coreCore-dump size, in bytes; 0 disables dumps.
cpuCPU time per process, in seconds; this is different from the vCore limit.
dataProcess data-segment size, in bytes.
fsizeMaximum file size, in bytes.
locksFile locks.
msgqueuePOSIX message-queue memory, in bytes.
niceThe process's allowed nice-priority limit.
rtprioReal-time scheduling priority limit.
sigpendingQueued signals.

Health-check fields

FieldMeaning
CommandA shell command inside the container. Exit code 0 means healthy. Blank disables the configured health check.
Interval (seconds)Time between checks.
Timeout (seconds)Time allowed for one check to finish.
RetriesConsecutive failures before the container is considered unhealthy.
Start period (seconds)Startup time before failed checks count toward the retry limit.

Use a command supplied by the image or a tool installed in it. A curl health check cannot work in an image without curl.

Add a public route

  1. In Routes, select Add route.
  2. Enter Hostname, without a scheme or path, and set Public path, usually /.
  3. Set Target port if the route should use a port other than the application's Container port, or if no application port is set.
  4. Choose TLS mode. Use Automatic certificate and Let's Encrypt when available for your cluster. HTTP only requests no certificate.
  5. Keep Default Entrypoint (80/443) unless your cluster has a specific configured entrypoint for this route.
  6. Point your hostname's DNS records to the cluster's public ingress address. If the sslip.io button is available, it can generate a hostname from an available ingress address instead.
  7. Create the application, or select Save changes when editing an existing one, then deploy the revision.
  8. Check the route's DNS and Certificate status. Use Recheck DNS after correcting DNS records and Retry certificate when a certificate request needs retrying. Select Open route to visit it.

Automatic certificates depend on the cluster's ingress configuration and reachable DNS. If Let's Encrypt is unavailable, ask the person who manages your cluster to check it.

Full view adds Internal path, middleware references, and Strip public path before forwarding. For TLS routes it also shows Redirect HTTP after the certificate is verified. Use custom resolvers, uploaded certificates, entrypoints, and middleware names only when they have already been configured for your cluster.

Change and deploy an application

Open the application's Application tab. Update Image & Deployment, Runtime, Resources, Storage, Health check, Environment variables, or Routes, then select Save changes.

For process overrides after creation, use Advanced. Process and isolation includes Entrypoint command, Command arguments, Working directory, and Run as user. Save these changes and deploy the resulting revision in the same way.

The confirmation identifies the saved revision and tells you to deploy it. Select Deploy as revision vN to apply that revision, or Build and deploy for a Git source. Saving changes does not change the running service, and edits made after a deployment is queued do not alter that queued deployment.

The header also provides these runtime actions after deployment:

ControlEffect
RedeployDeploys the current saved configuration again when no newer revision is pending.
StopStops the application runtime.
StartStarts the previously deployed application after it was stopped.
RestartRecreates running tasks without applying saved configuration changes.

Use a deployment to apply a changed image, environment, route, or runtime setting. Restart does not apply a pending revision.

Check a deployment or restore a revision

In Deployments, compare Desired configuration with Last successful deployment. Running replicas shows the node, image, service revision, state, and any task error. Expand Starting and previous replicas when investigating a failed start.

Use Revision history → Compare revisions to inspect changes. Choose From and To, or use Compare on a revision row.

To restore an available earlier configuration, select its Roll back action and confirm Roll back. Upvale restores that configuration as a new revision and starts a deployment. This does not reverse changes to application data or database schemas.

Open Logs for container output. Monitoring is available with View monitoring. Terminal and protected configuration controls depend on your permissions.

If an application displays a Compose ownership notice, edit and deploy it through its project environment's Compose workflow. Its individual deployment and configuration controls are restricted by that ownership.

Deployment automation

For a container image source, open Application → Image & Deployment → Deployment automation to trigger deployments from a CI pipeline. For Git sources, use Deploy on push under Source.

  1. Select Enable webhook.
  2. Copy the webhook URL and the one-time secret. Store the secret in your CI system's secret store.
  3. Build and push the new image in CI.
  4. Send the request shown under Request example, using the new image tag.
  5. Follow the deployment in Upvale. Last used, Last image tag, and Last commit help confirm that CI reached the webhook.

The request uses Authorization: Bearer with the webhook secret. Use a stable Idempotency-Key, such as the commit SHA, so a repeated CI request does not start another deployment for the same release. The example body includes tag, commitSha, and branch.

Rotate secret invalidates the previous secret. Update your CI secret after rotating it. Disable stops further requests through the webhook. This webhook belongs to the application; it is separate from an account API token.

Advanced application settings

Open Advanced after creating the application. Save and deploy a new revision to apply these options.

Process and isolation

OptionMeaning
Entrypoint commandReplaces the image's entrypoint. Add one array item per row. Empty uses the image default.
Command argumentsArguments passed to the process. One row is one argument; spaces are not split.
Working directoryDirectory in which the process starts. Blank uses the image default.
Run as userContainer user name or numeric UID, optionally with :group or :GID.
Init processStarts a small init process to handle signals and reap orphaned child processes. Choose the image/Docker default, enabled, or disabled.
Stop grace (seconds)Time allowed for a process to shut down before it is forcibly stopped. Maximum two hours; the accepted limit is lower for some large replica configurations.
Read-only root filesystemPrevents writes to the container's root filesystem. Put required writable paths on writable mounts.
No new privilegesPrevents a process from gaining additional privileges through executables such as setuid programs.

Command fields do not expand environment variables or interpret shell syntax. For a shell script, explicitly run a shell: use command rows sh, -c, and put the script in one argument row.

Published ports

Use Add published port for direct TCP or UDP access that does not use an HTTP route.

OptionMeaning
Container portThe port the process listens on inside the container.
Published portThe port clients connect to on the server.
ProtocolTCP or UDP.
Publish mode: IngressUses Swarm's routing mesh to forward the published port to a task.
Publish mode: HostPublishes on nodes that run a replica. A fixed port permits only one replica using that port on a node.

Allow only the required traffic in the node or cloud firewall. Published ports bypass the application's HTTP routes and their HTTP security settings. Changes can briefly interrupt connections. See Networking for the distinction between service networks, ingress, and node connectivity.

Restart policy

OptionMeaning
Platform default (restart any)Uses Upvale's default restart behavior.
Any task exitRestart whether the process exits successfully or with an error.
Failure onlyRestart after a failed exit.
Do not restartLeave an exited task stopped.
Delay (seconds)Delay before retrying.
Maximum attemptsLimit failed restart attempts.
Window (seconds)Time used to judge whether a restart succeeded before counting another failed attempt.

For a command that should finish once, use a scheduled job so you can track each execution separately.

Host access, capabilities, and sysctls

Host bind mount is available in Application → Storage to roles with Privileged workloads. Set the existing absolute Host path, its Container path, and whether the mount is Read-only. Upvale does not create, move, or delete that host path. It must exist on each node that can run the application.

Under Advanced → Linux capabilities and sysctls:

  • Add capabilities grants specific Linux capabilities to the container.
  • Drop capabilities removes capabilities the container would otherwise have.
  • Sysctls sets supported kernel parameters by name and value. Docker and the host determine which parameters are allowed.

These options require Privileged workloads permission. Host mounts and added capabilities can give a container access to its server; use only the permissions the image actually needs. The form asks for an explicit acknowledgement when privileged settings are configured.

HTTP security settings

The Security tab applies to generated Traefik routing. These settings do not inspect database traffic or traffic using direct published ports. Save and deploy them like other application configuration.

Section and optionWhat it does
Rate limiting → Limit requests per visitor IPLimits requests per client IP. Excess requests receive HTTP 429.
Average requestsAllowed average number of requests during Period (seconds).
Burst capacityTemporary extra capacity for short traffic spikes.
Request size → Limit request body sizeRejects request bodies larger than Maximum request body with HTTP 413. Choose KiB, MiB, or GiB. Leave disabled for streaming uploads.
IP access policy → Open with blocklistAllows visitors except the listed blocked addresses or CIDR ranges.
IP access policy → Allowlist onlyAllows only listed addresses or ranges. At least one allowed range is required.
Blocked IPs and rangesDenies matching traffic even if an allow rule also matches.
Security headersAdds the selected headers and the strict-origin-when-cross-origin referrer policy.
Prevent content-type sniffingAdds X-Content-Type-Options: nosniff.
Frame embedding policyLet the application manage framing, allow the same origin, or deny all frame embedding.
Require future HTTPS connections (HSTS)Tells browsers to use HTTPS for future visits for HSTS max age (seconds). Requires working HTTPS. 0 clears the cached policy; subdomains and preload are not included.

These headers override matching headers returned by the application. If you use custom routing YAML, maintain the corresponding middleware yourself or restore generated routing before using these controls. The Routes and Traefik guide explains routing and traffic changes in more detail.

Traefik tab

Upvale creates the application's routing file on its first deployment. While it is generated, changes in Routes and Security update that file.

Saving a manual edit in Traefik switches the file to manual management. Later route edits do not overwrite your YAML. Use Browse cluster files for the wider cluster routing configuration. Restore defaults regenerates this application's file from its saved route settings and starts the normal deployment flow; it discards manual changes to that file.

See Routes and Traefik for the file editor, versions, validation, and custom routing examples.

Logs, metrics, and terminals

In Logs, choose the service task, the number of tail lines, and all output, stdout, or stderr. Search filters the loaded output. Download saves the lines currently displayed. Refresh or reconnect if the selected container has been replaced.

In Monitoring, select a running replica or a previous replica and the time range you want to inspect. This helps distinguish a single busy container from a problem affecting the whole application.

To open a shell, select Deployments → Running replicas → Terminal on the intended replica. Terminals require the terminal permission and a running reachable container. Files changed inside a container may disappear when it is replaced; save persistent changes in the image, configuration, or mounted storage.

Back up application data

Open Backups to save all of the application's named volumes together. The application must have a successful deployment and be pinned to one active storage node in Placement. Host bind mounts are not supported.

The app stops while its volumes are copied. Its previous running or stopped state is restored afterward.

  1. Add an S3 destination, if you have not already.
  2. Open the application's Backups tab and select one or more Destinations.
  3. Select Back up now for an immediate backup, or configure the schedule below and select Save changes.
  4. Follow the operation. Backup history shows the saved image version, size, status, and copies in each destination.
SettingMeaning
DestinationsBuckets where each backup is saved.
Schedule (cron)A five-field cron expression. 0 3 * * * runs daily at 03:00.
TimezoneThe schedule's timezone, such as UTC or Europe/Skopje.
Keep latest backupsMaximum number of retained backups. Blank keeps all, unless an age limit applies.
Maximum age (days)Removes older copies after a successful backup. Blank sets no age limit.
EnabledTurns scheduled backups on or off. Manual backups remain available.

Restore an application

  1. Select Restore beside a completed backup.
  2. Choose the new application's Name, Project, and Storage node.
  3. Select Restore application. Upvale opens the new application with a link to the restore operation.
  4. Wait for the restore to finish, review the application, then deploy it when ready.

The new app starts stopped, with its own volumes and internal hostname. It uses the source application's current configuration and the image saved with the backup. Public routes, published ports, and Git deployment automation are not copied. Add routes after reviewing the restored data.

Deleting the source app keeps its retained backups. Open S3 Destinations → Backups → Restore to restore an application that has been deleted. If its project was also deleted, choose an active project.

Remove an application

Open Application → Danger zone → Delete application and type the name to confirm. This removes the service and routes but keeps named volumes. Follow the cleanup operation before treating the application as removed. Review retained volumes in Storage.

If no manager can perform cleanup, Remove application record only removes Upvale's records and leaves infrastructure on the servers. It requires an explicit acknowledgement. Use this only when you intend to handle that infrastructure separately.

Common problems

ProblemWhat to check
Image cannot be pulledRepository, tag, saved registry, and whether the nodes can reach that registry.
Container exits immediatelyLogs, image command, required environment variables, and the selected architecture.
Public route returns an errorRunning replica, container listening address and port, route target port, and DNS/certificate status.
Changes seem ignoredCompare the desired and last successful revisions. Save, then deploy. Also check whether Traefik has been manually edited.
Replica remains pendingAvailable nodes, placement constraints, resource limits, host-port conflicts, and required mounts.
Data disappears after replacementUse a persistent mount and the correct storage node. The container filesystem is temporary.
Application is Compose-managedMake the change in Compose for the owning project environment.