Project Settings

The Settings tab requires the same permission as updating the project — Owner, Admin, Manager, or Developer roles. See Members.

Change settings from the CLI, API, or an assistant #

You can update the build settings you use most often without opening this tab. All three paths save only the fields you send and leave the rest of the project unchanged:

depfloy projects update 14532 \
  --branch release \
  --build-command 'npm run build:production' \
  --auto-deploy=false

Omit the project id inside a repository linked with depfloy link. The command can change the framework, branch, install/build/post-deploy commands, Node.js memory limit, auto-deploy, and the PHP frontend-rebuild setting. Pass an empty command value, such as --build-command=, to return that command to its framework default.

An assistant connected over MCP can make the same changes with update_project after you confirm the call. For direct integrations, send only the fields you want to change to PUT /api/v1/projects/{id}.

These actions do not start a deployment or replace the release currently serving traffic. The saved settings are used by the next deployment.

Git repository #

• Repository URL — the URL or org/repo identifier
• Source Control Provider — must be one of the providers connected under Configuration → Source Control
• Branch — the branch Depfloy deploys from. Auto-deploy listens to pushes on this branch.

Changing the branch is the right tool when you want to promote a release branch to production without recreating the project. The next push to the new branch triggers a deployment automatically (if Auto Deploy is on).

Groups and environments #

Two optional fields say what this project is relative to your other projects.

• Group — the name of the application whose environments you are running. The production, staging and dev copies of one shop share a group; an agency gets one group per client. Pick an existing group or create one from the same control by typing a name.
• Environment — Production, Staging or Dev. It shows as a badge beside the project name in the Console.

Leave either unset rather than guessing. An ungrouped, unlabelled project is an ordinary project and shows no badge, which is what every project already created looks like — nothing was assigned for you and nothing is treated as production because it was not labelled.

A group can hold more than one production environment; two regions of the same application are both production. The Console points it out when you create a second one, in case the project was meant to be staging, and then accepts it.

Deleting a group does not delete anything you deployed. The projects in it stay exactly as they are and become ungrouped, and the response says how many were affected.

Groups need no new permission: reading them comes with project:read and changing them with project:update, the same permission that governs the rest of this tab. They are also available over the API and to an AI assistant over MCP.

Framework and build #

• Framework — Depfloy uses this to choose default install and build commands. If you switch frameworks, the defaults switch too.
• Custom Install Command — overrides Depfloy’s default install command for the chosen framework (for example to use pnpm install instead of npm install). Leave blank to use the default.
• Custom Build Command — overrides the default build command (for example to use npm run build:prod instead of npm run build). Leave blank to use the default.

You do not need to put composer install, npm install, or php artisan migrate in these fields — Depfloy runs the framework-appropriate equivalents as part of the build pipeline.

Changing the framework #

You can change a project’s framework from this tab. Depfloy asks you to confirm first, because the install, build and start commands all follow from it — a project whose repository doesn’t match the framework you pick will fail to build. The change applies from the next deployment; the release currently serving is left alone.

A project moves between frameworks of the same language:

• PHP — PHP, Laravel, Symfony, WordPress, Statamic
• JavaScript — Next.js, Nuxt, Remix, React Router, Astro

The other language’s frameworks aren’t selectable. Moving between PHP and JavaScript changes how the application is served, and needs a new project.

How Node.js applications are started #

For Node.js projects, Depfloy reads the start script in your package.json and — when it’s a straightforward single command — runs your application directly, instead of starting it through an npm run start wrapper.

What you’ll notice:

• Lower memory use. Around 70 MB less RAM per application on the server, because the extra npm and shell processes that used to sit in front of your app are gone.
• Accurate memory reporting. The memory figure reported for the application is now the application’s own usage. The much lower numbers you may have seen before were the wrapper process, not your app. This is a correction, not an increase — your application is using the same memory it always did; it’s finally being measured correctly.
• Nothing gets skipped. If your start script chains several commands (for example prisma migrate deploy && node server.js), or your package.json defines a prestart or poststart script, Depfloy keeps the previous behaviour and starts your app through npm as before. Those scripts still run.

This applies to every Node.js framework Depfloy runs as an application: Next.js, Nuxt, Remix, React Router and Astro.

Memory limit #

Node.js projects have a Memory Limit field. It is the ceiling the application is allowed to use — for example 512MB or 1GB. A process that goes past it is replaced with a fresh one.

Leave it empty to follow the server’s default rather than pinning a value on this project. The setting applies from the next deployment.

Which user your application runs as #

Node.js applications run as the depfloy user — the same user your deployments and Commands run as.

What that means in practice:

• Files your application writes — logs, caches, uploads — belong to depfloy. Writing outside your project directory is refused. That boundary is deliberate: an application confined to its own directory cannot reach another project’s files.
• Work that requires root is not available. Binding to a port below 1024 is the usual example, and it does not come up in a normal setup because Depfloy assigns your application a port and puts nginx in front of it.
• It applies once the server is on DPM 1.10.0 or later and the project has been deployed again.

Files your application created earlier may be owned by a different user. If it cannot write to a cache or log directory it used to write to, set the ownership once on the server:

sudo chown -R depfloy:depfloy <project_directory>

Custom deployment command #

A custom deployment command runs after Depfloy finishes the build, the symlink switch is done, and the new release is live. Use it for post-deploy work that’s specific to your project — warming caches, signalling a dashboard, restarting a non-Depfloy-managed service.

# Example
php artisan cache:clear
php artisan queue:restart

Important guidelines:

• Don’t call php artisan reverb:restart — Depfloy already restarts Laravel plugins (Reverb, Horizon, Octane, Nightwatch) for you. Calling them again from your script can hang the deployment.
• Keep commands short. A custom command is for a quick post-deploy step, not a database backfill. Long-running work should live in your build pipeline or in a one-off Command.

See Developer Guide → Custom deployment commands for full guidance.

Markdown for AI agents #

A project Depfloy serves as static files can answer a request for markdown with a markdown version of the page. A client that sends Accept: text/markdown — an AI agent or an LLM reading your site — gets markdown; browsers keep getting HTML from the same address. Far fewer tokens, and text without the layout around it.

Turn it on with the Markdown for AI agents switch. It is off until you do, and saving it reloads nginx on the server.

There is nothing to add to your project. Depfloy writes the markdown from your built pages on every deployment. Headings, lists, links, code blocks and tables carry over; navigation, headers, footers, scripts and styles are left out, so what an agent reads is the page’s content rather than its furniture. If your own build already produces a .md file for a page, Depfloy leaves that file alone.

Check it from a terminal:

curl -H 'Accept: text/markdown' https://yoursite.com/

The switch appears only on projects served as static files: an Astro site without an adapter, a Next.js static export, a React Router SPA. Where your application produces the response — Laravel, WordPress, a Next.js server build — there is no second representation to choose from, so the switch isn’t offered.

If Settings tells you no markdown was found in the project’s web root, the conversion hasn’t produced anything yet. Deploy again; if the message stays, the deployment log says why.

Auto-deploy #

• Enable Auto Deploy — when on, every push to the configured branch triggers a deployment. Depfloy installed the webhook when you created the project; disabling Auto Deploy just disconnects Depfloy’s response to it (the webhook itself stays registered with your Git provider).

If your Git provider rotates webhook secrets or the connection between Depfloy and the provider breaks, the Refresh action on this tab re-registers the webhook.

Health check #

Set a health-check endpoint and Depfloy uses it to decide when a new deployment is “really” live before flipping the symlink. The endpoint should:

• Return 200 OK on a healthy application
• Run quickly — under a second is fine; under 30 seconds is the maximum
• Not require authentication or session state

Typical Laravel health check: /up (built-in since Laravel 11). Typical Node.js health check: /healthz or /api/health.

If the health check fails during a deploy, the deployment is marked failed and the previous release stays active.

Shared directories and files #

Beyond Depfloy’s default shared paths (.env, storage/), you can declare additional paths that should persist across deployments. The Settings tab has two lists:

• Shared Directories — whole directories, for example uploads or data/cache
• Shared Files — individual files, for example storage/oauth-private.key

Useful for:

• User-uploaded files outside storage/
• A directory of generated PDFs or reports you don’t want to regenerate every deploy
• Keys, certificates or config files your application writes at runtime
• Anything else where the contents are runtime state rather than versioned code

List each path relative to the project root. Depfloy creates the corresponding entry in the shared folder once and symlinks it into every release.

Existing content is kept #

If the path you share already exists in your running application, its contents are preserved. On the first deployment after you add it, Depfloy moves what’s already there into the shared folder and symlinks it into every release from then on — nothing is wiped.

This matters most for files your application generated at runtime and that aren’t in your repository. The classic example is Laravel Passport: the oauth-private.key and oauth-public.key pair produced by php artisan passport:keys. Add those two files to Shared Files and the keys you already have on the server keep working, deployment after deployment.

Maintenance Mode #

Near the bottom of the Settings tab, just before the Delete Project card, is a Maintenance Mode card. The card shows a title and short description on the left and a switch on the right. Flip the switch to put the project behind a holding page; flip it back to bring the project online again. Toggles take effect immediately.

While maintenance mode is on, the Nginx Configuration tab is read-only — your custom snippets and SSL toggle are locked until you turn maintenance off again.

For a deeper guide on the holding page and customisation, see Maintenance Mode.

Delete project #

The Delete project button at the bottom of the Settings tab removes the project from Depfloy entirely. Files in the project directory on the server are removed along with the project’s history.

Related actions #

A few project-level actions live in the three-dot menu in the project header rather than in this tab:

• Change Server — move the project to a different server
• Rollback — restore a previous successful deployment (see Deployments)