Skip to content

docs: deployments with local builds #2645

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 30, 2025
Merged

docs: deployments with local builds #2645

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
fe23351
docs: deployments with local builds
myftija Oct 30, 2025
9746705
Update installation link
myftija Oct 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions docs/deployment/overview.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -182,6 +182,25 @@ TRIGGER_SECRET_KEY="tr_stg_abcd123"

Currently, we only support two environments: `prod` and `staging`. Multiple environments are on our roadmap which you can track [here](https://feedback.trigger.dev/p/more-environments).

## Local builds

By default we use a remote build provider to speed up builds. However, you can also force the build to happen locally on your machine using the `--force-local-build` flag:

```bash
npx trigger.dev deploy --force-local-build
```

<Tip>
Deploying with local builds can be a useful fallback in cases where our remote build provider is experiencing availability issues.
</Tip>

### System requirements

To use local builds, you need the following tools installed on your machine:

- Docker ([installation guide](https://docs.docker.com/get-started/get-docker))
- Docker Buildx ([installation guide](https://github.com/docker/buildx#installing))

## Environment variables

To add custom environment variables to your deployed tasks, you need to add them to your project in the Trigger.dev dashboard, or automatically sync them using our [syncEnvVars](/config/config-file#syncenvvars) or [syncVercelEnvVars](/config/config-file#syncvercelenvvars) build extensions.
Expand Down Expand Up @@ -214,6 +233,8 @@ You can run the deploy command with `--log-level debug` at the end. This will pr

There should be a link below the error message to the full build logs on your machine. Take a look at these to see what went wrong. Join [our Discord](https://trigger.dev/discord) and you share it privately with us if you can't figure out what's going wrong. Do NOT share these publicly as the verbose logs might reveal private information about your project.

Sometimes these errors are caused by upstream availability issues with our remote build provider. In this case, you can try deploying with a local build using the `--force-local-build` flag. Refer to the [Local builds](#local-builds) section for more information.

#### `Deployment encountered an error`

Usually there will be some useful guidance below this message. If you can't figure out what's going wrong then join [our Discord](https://trigger.dev/discord) and create a Help forum post with a link to your deployment.
Expand Down