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.
| Tab | What you use it for |
|---|---|
| Application | Source, image, replicas, placement, resources, storage, environment variables, health checks, routes, and deployment automation. |
| Deployments | Git builds and build logs, running containers, deployment status, revision comparisons, rollback, and a terminal for a running replica. |
| Backups | Back up all named volumes, set a schedule, and restore to a new application. |
| Logs | Container output, with replica selection and search. |
| Monitoring | Historical resource metrics, including individual replicas. |
| Traefik | The generated routing file, or a manually maintained routing configuration. |
| Security | Request limits, IP rules, and HTTP security headers. |
| Advanced | Process 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
- Open Workloads, then open your project.
- Choose the intended environment in the environment selector beside the project name.
- Select Add Service → Application. The New application page keeps the project selected.
- Under Basics, enter a Name.
- Under Source, choose Container image and enter Repository, Tag, and Registry. For Git repository, follow Build from a repository below.
- Under Runtime, enter the Container port for a web service, choose Replicas, and set Placement. The initial replica count is
1and placement is Automatic — any available node. - Configure any resources, storage, health check, environment variables, and routes needed by the image, using the sections below.
- Select Create application, or Create and build application for Git. Upvale opens the application's detail page.
- 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:
| Field | Value |
|---|---|
| Name | hello-web |
| Repository | nginx |
| Tag | stable |
| Registry | public / anonymous |
| Container port | 80 |
| Replicas | 1 |
| Placement | Automatic — 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:
| Setting | Value |
|---|---|
| Repository connection | A saved connection from Repositories. Its provider determines the repositories available. |
| Repository and Branch | The repository and branch to build. The repository's default branch is selected initially. |
| Build node | An online node in the application's cluster that will run the Docker build. |
| Dockerfile | A path relative to the build context; initially Dockerfile. |
| Build context | A 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 push | Build 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 location | Registry selection | Repository example | Tag example |
|---|---|---|---|
| Public Docker Hub image | public / anonymous | nginx | latest |
| Public image on another registry | public / anonymous | ghcr.io/acme/web | v1.0.0 |
Image using a saved connection whose host is ghcr.io | That saved connection | acme/web | v1.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
| Setting | What it changes |
|---|---|
| Container port | The 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. |
| Replicas | How many copies of the application should run, from 1 to 100. Each has its own container and resource limits. |
| Automatic — any available node | Docker chooses an eligible node. |
| Worker nodes only | Run only on Swarm workers. |
| Manager nodes only | Run only on Swarm managers. |
| Specific node | Keep 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/datawhen 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
| Option | Meaning |
|---|---|
| vCore limit | CPU 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 ulimit | Adds a Linux process limit. Soft is the active limit and Hard is its ceiling. -1 means unlimited. |
The ulimit selector supports these limits:
| Limit | What it controls |
|---|---|
nofile | Open file descriptors. |
nproc | Processes. |
memlock | Locked memory, in bytes. |
stack | Process stack size, in bytes. |
core | Core-dump size, in bytes; 0 disables dumps. |
cpu | CPU time per process, in seconds; this is different from the vCore limit. |
data | Process data-segment size, in bytes. |
fsize | Maximum file size, in bytes. |
locks | File locks. |
msgqueue | POSIX message-queue memory, in bytes. |
nice | The process's allowed nice-priority limit. |
rtprio | Real-time scheduling priority limit. |
sigpending | Queued signals. |
Health-check fields
| Field | Meaning |
|---|---|
| Command | A 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. |
| Retries | Consecutive 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
- In Routes, select Add route.
- Enter Hostname, without a scheme or path, and set Public path, usually
/. - Set Target port if the route should use a port other than the application's Container port, or if no application port is set.
- Choose TLS mode. Use Automatic certificate and Let's Encrypt when available for your cluster. HTTP only requests no certificate.
- Keep Default Entrypoint (80/443) unless your cluster has a specific configured entrypoint for this route.
- 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.
- Create the application, or select Save changes when editing an existing one, then deploy the revision.
- 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:
| Control | Effect |
|---|---|
| Redeploy | Deploys the current saved configuration again when no newer revision is pending. |
| Stop | Stops the application runtime. |
| Start | Starts the previously deployed application after it was stopped. |
| Restart | Recreates 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.
- Select Enable webhook.
- Copy the webhook URL and the one-time secret. Store the secret in your CI system's secret store.
- Build and push the new image in CI.
- Send the request shown under Request example, using the new image tag.
- 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
| Option | Meaning |
|---|---|
| Entrypoint command | Replaces the image's entrypoint. Add one array item per row. Empty uses the image default. |
| Command arguments | Arguments passed to the process. One row is one argument; spaces are not split. |
| Working directory | Directory in which the process starts. Blank uses the image default. |
| Run as user | Container user name or numeric UID, optionally with :group or :GID. |
| Init process | Starts 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 filesystem | Prevents writes to the container's root filesystem. Put required writable paths on writable mounts. |
| No new privileges | Prevents 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.
| Option | Meaning |
|---|---|
| Container port | The port the process listens on inside the container. |
| Published port | The port clients connect to on the server. |
| Protocol | TCP or UDP. |
| Publish mode: Ingress | Uses Swarm's routing mesh to forward the published port to a task. |
| Publish mode: Host | Publishes 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
| Option | Meaning |
|---|---|
| Platform default (restart any) | Uses Upvale's default restart behavior. |
| Any task exit | Restart whether the process exits successfully or with an error. |
| Failure only | Restart after a failed exit. |
| Do not restart | Leave an exited task stopped. |
| Delay (seconds) | Delay before retrying. |
| Maximum attempts | Limit 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 option | What it does |
|---|---|
| Rate limiting → Limit requests per visitor IP | Limits requests per client IP. Excess requests receive HTTP 429. |
| Average requests | Allowed average number of requests during Period (seconds). |
| Burst capacity | Temporary extra capacity for short traffic spikes. |
| Request size → Limit request body size | Rejects 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 blocklist | Allows visitors except the listed blocked addresses or CIDR ranges. |
| IP access policy → Allowlist only | Allows only listed addresses or ranges. At least one allowed range is required. |
| Blocked IPs and ranges | Denies matching traffic even if an allow rule also matches. |
| Security headers | Adds the selected headers and the strict-origin-when-cross-origin referrer policy. |
| Prevent content-type sniffing | Adds X-Content-Type-Options: nosniff. |
| Frame embedding policy | Let 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.
- Add an S3 destination, if you have not already.
- Open the application's Backups tab and select one or more Destinations.
- Select Back up now for an immediate backup, or configure the schedule below and select Save changes.
- Follow the operation. Backup history shows the saved image version, size, status, and copies in each destination.
| Setting | Meaning |
|---|---|
| Destinations | Buckets where each backup is saved. |
| Schedule (cron) | A five-field cron expression. 0 3 * * * runs daily at 03:00. |
| Timezone | The schedule's timezone, such as UTC or Europe/Skopje. |
| Keep latest backups | Maximum 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. |
| Enabled | Turns scheduled backups on or off. Manual backups remain available. |
Restore an application
- Select Restore beside a completed backup.
- Choose the new application's Name, Project, and Storage node.
- Select Restore application. Upvale opens the new application with a link to the restore operation.
- 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
| Problem | What to check |
|---|---|
| Image cannot be pulled | Repository, tag, saved registry, and whether the nodes can reach that registry. |
| Container exits immediately | Logs, image command, required environment variables, and the selected architecture. |
| Public route returns an error | Running replica, container listening address and port, route target port, and DNS/certificate status. |
| Changes seem ignored | Compare the desired and last successful revisions. Save, then deploy. Also check whether Traefik has been manually edited. |
| Replica remains pending | Available nodes, placement constraints, resource limits, host-port conflicts, and required mounts. |
| Data disappears after replacement | Use a persistent mount and the correct storage node. The container filesystem is temporary. |
| Application is Compose-managed | Make the change in Compose for the owning project environment. |