App Service

An App service runs one application as a Docker service. Easypanel can build the image from source code, use an inline Dockerfile, or pull an existing image. It also manages deployments, domains, environment variables, storage, scripts, resource limits, and common runtime operations.

Use a Compose service when several containers must be defined and deployed together. Use a Box service when you want Easypanel to assemble language runtimes and processes without maintaining a Dockerfile.

Create an App service

1. Open a project and select New Service.
2. Select App, enter a service name, and create the service.
3. Open Source and choose where the application comes from.
4. Configure a builder when the source contains application code.
5. Add environment variables, storage, domains, and any required runtime settings.
6. Select Deploy.
7. Review the deployment output and runtime logs.

New App services include an automatic service domain when automatic domains are configured for the server. Make sure its target port matches the port on which the application listens.

Overview

The overview provides the main lifecycle actions:

• Deploy builds or pulls the image and applies the saved configuration.
• Start and Stop enable or disable the running service.
• Restart recreates the running service from the current deployment.
• Force Rebuild performs a deployment without using the Docker build cache.
• Logs opens the service log stream.
• Shell opens sh, bash, or one of the service's saved scripts.
• Open opens the primary domain.
• Enable Auto Deploy or Disable Auto Deploy controls the GitHub webhook when GitHub is the source.

The overview page also shows service metrics, notes, recent logs, and detected service errors.

Source

Upload

Upload a code archive when the source is not stored in a reachable repository. Easypanel accepts common archive formats including ZIP, TAR, 7z, and RAR. After the upload finishes, select a builder and deploy the service.

GitHub

Enter the repository as owner/repo, select a branch, and set the Build Path. The build path is / for a repository-root application and can point to a subdirectory in a monorepo.

Public repositories do not require a GitHub token. Configure the server's GitHub token before selecting a private repository. GitHub sources can also use auto deploy, which triggers a deployment when the configured repository webhook receives a push.

Git

Use Git for repositories hosted outside GitHub or when you want to connect over SSH. Configure the repository URL, branch, and build path.

For a private repository, generate the service's SSH key and add the public key to the repository as a read-only deploy key. Refreshing the SSH key invalidates the old key, so update the repository before the next deployment.

Docker Image

Enter an image with a tag, for example:

ghcr.io/example/api:1.4.0

For a private registry, also provide its username and password. Image sources are pulled rather than built, so the builder section is not shown.

Prefer an immutable version or digest over latest when deployments must be reproducible.

Dockerfile

The inline Dockerfile source stores a complete Dockerfile in Easypanel. Use it for a small, self-contained image definition. Files from a repository or upload are not automatically available to this source type, so include everything the Dockerfile needs in the image definition.

Build

The Build section is available for Upload, GitHub, and Git sources:

• Dockerfile runs docker build using the configured Dockerfile path.
• Buildpacks builds with the selected Cloud Native Buildpacks builder.
• Nixpacks detects the application and supports version, install, build, start, Nix package, and APT package overrides.
• Railpack detects the application and supports version, install, build, start, Mise package, build APT package, and deploy APT package overrides.

Choose explicit commands only when automatic detection produces the wrong result. See Builders for builder-specific guidance.

Deployments

The Deployments tab contains the recent deployment history and the Deployment Trigger URL. Sending a request to that URL starts a deployment, which makes it useful for CI systems and external webhooks.

The URL contains a secret token. Refreshing the token immediately invalidates the previous URL, so update every external integration after rotating it.

When a deployment fails, open its action output first. Build failures appear there; runtime failures usually appear in the service logs after the image has been created.

Environment

Enter environment variables using .env syntax:

NODE_ENV=production
DATABASE_URL=postgres://user:password@project_database:5432/app

The values are provided to the build and the running container. For every source type except Docker Image, Create env file can also write the content to a path such as .env.

Easypanel replaces these values in the environment:

• $(PROJECT_NAME) with the project name;
• $(SERVICE_NAME) with the service name;
• $(PRIMARY_DOMAIN) with the host of the service's primary domain.

Treat environment values and the generated env file as secrets. Do not print them in build logs or commit them to source control.

Domains

A domain sends HTTP traffic through Easypanel's proxy to the App service. Set the public hostname and path, then configure the internal protocol and target port used by the application.

A domain can also configure HTTPS, a certificate resolver, wildcard routing, Traefik middlewares, or a custom destination. Mark one domain as primary so the Open action and $(PRIMARY_DOMAIN) use the intended hostname.

The target port must be the port on which the process listens inside the container. The application should normally listen on 0.0.0.0, not only 127.0.0.1. See Custom Service Domain for automatic service hostnames.

Redirects

Redirect rules contain an enabled state, regular expression, replacement URL, and permanent or temporary status. They run at the proxy before traffic reaches the application.

Test a rule as a temporary redirect before making it permanent. Browsers can cache permanent redirects, and an incorrect regular expression can create a redirect loop.

Scripts

Scripts are named shell snippets that can be launched from the service's Shell menu. Use them for repeatable diagnostics or administrative commands that need the App container's environment.

Scripts are stored in the service configuration. Do not place passwords or API tokens directly in script content; reference environment variables instead.

Security

The Security tab manages HTTP Basic Auth credentials for the service's domains. Basic Auth is useful for staging sites and internal tools because the proxy challenges requests before they reach the application.

It does not replace application-level accounts, permissions, or API authorization.

Resources

Configure memory reservations and limits in MB, and CPU reservations and limits in cores. A reservation expresses expected baseline usage; a limit caps the resources available to the service. Set a value to 0 for no limit.

Allow enough memory for both the build and runtime workload. A limit that is too low can terminate builds or containers during traffic spikes.

Maintenance

Maintenance mode replaces normal domain traffic with a maintenance page while the container continues running. Configure its title, subtitle, and enabled state. Licenses with white-labeling can also set a custom logo, custom CSS, and branding visibility.

Use maintenance mode during migrations or deployments that must run without serving normal traffic. It is different from Stop, which disables the service.

Storage

Container filesystem changes can be lost when a service is recreated. Use a mount for uploads, generated content, or other persistent data:

• Volume creates Easypanel-managed storage and mounts it at a container path.
• Bind maps an existing server path to a container path.
• File stores file content in the service configuration and mounts it at a container path.

Storage changes require a deployment. Verify that the image's runtime user can read and write the mounted path.

The Storage tab can also schedule backups of volume mounts to a configured storage provider. A backup selects the volume, schedule, destination, and destination path, and can be run manually. Review Volume Backups Logs after testing a new schedule. See Volume Backups for sync behavior, limitations, and recovery guidance.

Advanced

Ports

Ports publish non-HTTP TCP or UDP traffic directly from the server:

• Published is the port on the server.
• Target is the port inside the App container.

Use Domains for websites and HTTP APIs so that Easypanel can manage HTTPS and proxy middleware. Published ports must not conflict with another service.

Deploy settings

The Deploy panel configures:

• the number of replicas;
• zero-downtime deployments;
• Tini as the container init process;
• a command override;
• added or dropped Linux capabilities;
• sysctl values;
• supplemental groups.

Replicas share the same service configuration and log stream. Avoid writing instance-specific state to the container filesystem, and use shared persistent storage only when the application supports concurrent access.

Capabilities and sysctls change the container's security boundary. Add only values required by the workload.

Service deletion

Destroying an App service removes its configuration, deployment, source files, domains, and service-managed data. Export application data and verify backups before confirming deletion.