# Box Service

URL: /docs/services/box

Source: https://github.com/easypanel-io/monorepo/blob/main/apps/website/content/docs/services/box.mdx

Run applications in a configurable, module-based runtime.



The Box service runs application code in an Easypanel-managed container. Instead
of supplying a Dockerfile, you choose the runtimes and modules that your
application needs. Box can provide Node.js, PHP, Python, Ruby, NGINX, managed
processes, persistent storage, a browser IDE, and deployment automation.

Use an [App service](/docs/services/app) when your repository already has a
Dockerfile or should be built with a standard application builder. Use Box when
you want to assemble and operate the runtime from the Easypanel interface.

## Create a Box service [#create-a-box-service]

1. Open a project and select **New Service**.
2. Select **Box** and enter a service name.
3. Choose a preset or select **No Preset**.
4. Create the service.
5. Initialize it by cloning a public or private Git repository, or skip the
   repository step and add files later through Git, the IDE, or a mount.
6. Open **Modules** and enable the sections needed by the application.
7. Configure at least one process or NGINX before exposing the service.

Box presets provide a starting configuration. Loading a preset replaces the
current Box configuration, rebuilds the image, and deploys the service. Files
in `/code` are not changed. Review the current configuration before applying a
different preset.

## Modules [#modules]

Modules control both the generated runtime and the sections shown in the Box
sidebar. You can enable only the features the service needs:

* **Node.js**, **PHP**, **Python**, and **Ruby** install language runtimes.
* **NGINX** adds a web server and reverse-proxy configuration.
* **Processes** runs application commands under the Box process supervisor.
* **Git** and **IDE** provide ways to manage the code in `/code`.
* **Environment**, **Mounts**, and **Ports** configure the container.
* **Domains**, **Redirects**, and **Basic Auth** configure public access.
* **Deployments** and **Scripts** provide deployment and automation hooks.
* **Resources** and **Advanced** control runtime limits and lifecycle scripts.

Changing a runtime module can require a new Box image. Use **Rebuild Docker
Image** after changing installed runtimes or build settings.

## Git [#git]

The Git section can clone a repository into the service's code directory. Set
the repository URL and branch during initialization or clone it later.

For a private repository, add the Box service's SSH key as a deploy key with
read access to the repository. The Git settings also let you configure the
author name and email used by commands executed inside the service.

<Callout type="warn">
  Cloning into a directory that already contains application files can overwrite
  or conflict with those files. Back up local changes before cloning another
  repository.
</Callout>

## IDE [#ide]

The browser IDE is optional. Its default folder is `/code`, and access is
protected by a generated token. Rotate the token if it is disclosed, and disable
the IDE when it is not needed.

## Runtime modules [#runtime-modules]

### Node.js [#nodejs]

Enable Node.js and select the required major version. You can also install Yarn
or pnpm alongside npm. Package installation should normally happen in the
**Build Script**, while the application command belongs in **Processes**.

### PHP [#php]

The PHP module controls the PHP version, maximum upload size, maximum execution
time, OPcache, custom `php.ini` content, and optional extensions such as ionCube
and SQL Server support.

Runtime changes are applied when the Box image is rebuilt.

### Python and Ruby [#python-and-ruby]

Enable Python or Ruby and select the runtime version required by the
application. Install dependencies in the **Build Script**, then start the
application with a managed process.

## NGINX [#nginx]

Enable NGINX for applications that serve HTTP traffic directly or through PHP
FPM. Configure:

* **Document Root**: the directory containing public files, usually a path
  inside `/code`.
* **Configuration**: the NGINX server configuration generated for the service.

The default configuration supports the `{{ document_root }}` and
`{{ fpm_socket }}` placeholders. Keep the listener aligned with the port used by
the service's domain.

## Processes [#processes]

A Box service can run one or more supervised processes. Each process has:

* a unique lowercase name;
* a working directory;
* a command;
* an enabled state.

Examples include a web server, a queue worker, or a scheduler. Saving the
process configuration reloads it inside the Box container.

<Callout type="info">
  Put long-running commands in **Processes**. The Advanced **Start Script** is
  for startup preparation and must finish instead of remaining attached.
</Callout>

## Environment [#environment]

Enter environment variables using `.env` syntax:

```dotenv
APP_ENV=production
APP_URL=https://example.com
```

Environment changes affect running processes after the service is restarted or
redeployed. Do not commit secrets to the repository.

## Mounts [#mounts]

Box supports the same three mount types as App services:

* **Volume** stores persistent data managed by Easypanel.
* **Bind** maps an existing server path into the container.
* **File** creates a file from content stored in the service configuration.

The source or volume name identifies storage on the server; the mount path is
the location visible inside the Box container. Use mounts for uploads and other
data that must survive image rebuilds.

Named volume mounts can be mirrored to a configured storage provider. See
[Volume Backups](/docs/backups/volumes) for scheduling, sync behavior, and
manual recovery guidance.

## Ports [#ports]

Use Ports for non-HTTP TCP or UDP traffic. **Published** is the server port and
**Target** is the port inside the container.

For websites and APIs, use **Domains** instead. Publishing a port bypasses the
normal domain, HTTPS, and middleware flow.

## Domains [#domains]

Each domain routes a hostname and path to a port in the Box service. A domain
can also configure:

* HTTP or HTTPS;
* the internal HTTP or HTTPS protocol;
* a certificate resolver;
* a wildcard hostname;
* Traefik middlewares.

The target port must match the port used by NGINX or the application's web
process. See [Custom Service Domain](/docs/guides/custom-service-domain) for
automatic service hostnames.

## Redirects [#redirects]

Redirect rules match a regular expression and send requests to a replacement
URL. Rules can be enabled or disabled and can use permanent or temporary HTTP
redirects. Test a new expression before using a permanent redirect to avoid
cached redirect loops.

## Basic Auth [#basic-auth]

Basic Auth protects every domain attached to the service with an additional
username and password prompt. It is useful for staging sites and internal
tools, but it does not replace the application's own authorization system.

## Scripts [#scripts]

Scripts execute shell content inside the Box service. A script can be run
manually, scheduled with a cron expression, or triggered with its webhook token.

Treat webhook tokens as secrets. Rotate a token after accidental disclosure,
and design scheduled scripts so that overlapping executions cannot corrupt
data.

## Deployments [#deployments]

The deployment script runs inside a Box container when a deployment is
triggered. Typical steps include pulling the latest Git revision, installing
dependencies, running migrations, or clearing caches.

The **Deployment URL** starts the deployment from an external CI system or
webhook. Refreshing the deployment token immediately invalidates the previous
URL.

## Resources [#resources]

Set CPU and memory reservations to describe the service's expected baseline.
Set limits to prevent the service from consuming all server capacity. A memory
limit that is too low can cause the operating system to terminate the
application during builds or traffic spikes.

## Advanced [#advanced]

The **Build Script** runs while Easypanel builds the Box image. Use it to install
dependencies and customize the image.

The **Start Script** runs when the service starts. Use it for short
initialization tasks. Configure web servers, workers, and other long-running
commands in **Processes**.

## Service lifecycle [#service-lifecycle]

You can start, stop, restart, rebuild, and destroy a Box service from its
overview. Stopping disables the deployment without removing the configuration.
Rebuilding regenerates the Box image and redeploys the service.

<Callout type="warn">
  Destroying a Box service permanently removes its files, generated image,
  domains, and volume backup schedules. Files already stored by a backup
  provider are not removed. Export application data and verify the remote copy
  before confirming deletion.
</Callout>