> For the complete documentation index, see [llms.txt](https://docs.lingoql.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lingoql.com/introduction/troubleshooting-deploys/deploy-checklist.md).

# Deploy checklist

Most deploy issues come from five places: source layout, build detection, env vars, startup behavior, or network binding.

### Start here

1. Confirm the app builds locally in production mode.
2. Confirm the app starts with the same env vars you use in LingoQL.
3. Confirm the process binds to `HOST:$PORT`.

LingoQL injects both `HOST` and `PORT` into each deploy.

If your framework only accepts a literal host, bind to `0.0.0.0` and read `PORT`.

### Choose the right buildpack

LingoQL supports two buildpacks:

* `Railpack` — the default option
* `Nixpacks` — the alternative option

LingoQL can deploy any app supported by these buildpacks.

If one buildpack mis-detects your app or fails unexpectedly, redeploy with the other buildpack.

Reference docs:

* [Railpack docs](https://railpack.com)
* [Nixpacks configuring builds guide](https://nixpacks.com/docs/guides/configuring-builds)

### Before you redeploy

#### Keep the repo deployable

* Commit the files the buildpack needs to detect your stack.
* Commit one lockfile per package manager.
* Keep generated artifacts and local caches out of the repo.

#### Pin your runtime

Pin the language or runtime version your app expects.

Use the standard version file or manifest for your stack.

A local build on one runtime version and a remote build on another can fail differently.

#### Separate secrets from code

Put secrets in environment variables.

Do not rely on local `.env` files being present in production.

Check database URLs, API keys, OAuth secrets, and app base URLs.

#### Start the right process

Your deploy must start a long-running server process.

A migration script, seed script, or one-off job will exit after it runs.

Run migrations as a separate step when your app needs them.

#### Listen on the platform port

Do not hardcode `localhost` or a fixed port.

Read `HOST` and `PORT` from the runtime environment.

{% tabs %}
{% tab title="Node.js" %}

```javascript
const host = process.env.HOST || '0.0.0.0';
const port = Number(process.env.PORT || 3000);
app.listen(port, host);
```

{% endtab %}

{% tab title="Python" %}

```python
import os
host = os.environ.get("HOST", "0.0.0.0")
port = int(os.environ.get("PORT", 3000))
app.run(host=host, port=port)
```

{% endtab %}
{% endtabs %}

### If the deploy still fails

Move to the page that matches the failure point:

* [Build fails before the app starts](/introduction/troubleshooting-deploys/build-failures.md)
* [App builds but never becomes healthy](/introduction/troubleshooting-deploys/runtime-and-startup-failures.md)
* [Custom domain does not resolve or HTTPS breaks](/introduction/troubleshooting-deploys/custom-domains-and-dns.md)
* [Repository clone fails before build starts](/introduction/troubleshooting-deploys/github-cloning-limits.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.lingoql.com/introduction/troubleshooting-deploys/deploy-checklist.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.