Skip to content

Commit f188d9a

Browse files
fredrfredr
authored
docs: document the different env variables to configure encore (#2165)
1 parent 4e7192f commit f188d9a

File tree

3 files changed

+328
-1
lines changed

3 files changed

+328
-1
lines changed

‎docs/go/develop/env-vars.md‎

Lines changed: 102 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,102 @@
1+
---
2+
seotitle: Environment Variables Reference
3+
seodesc: Learn how to configure Encore's development environment using environment.
4+
title: Environment Variables
5+
subtitle: Configure your development environment
6+
lang: go
7+
---
8+
9+
Encore works out of the box without configuration, but provides several environment variables for advanced use cases such as debugging, testing, or adapting Encore to specific workflow requirements.
10+
11+
## Daemon & Development Dashboard
12+
13+
These variables control how the Encore daemon operates and where it exposes its services.
14+
15+
### ENCORE_DAEMON_LOG_PATH
16+
17+
Controls the location of the Encore daemon log file.
18+
19+
**Default:** `<user_cache_dir>/encore/daemon.log`
20+
21+
**Example:**
22+
23+
```bash
24+
export ENCORE_DAEMON_LOG_PATH=/var/log/encore/daemon.log
25+
```
26+
27+
### ENCORE_DEVDASH_LISTEN_ADDR
28+
29+
Overrides the listen address for the local development dashboard.
30+
31+
**Default:** Automatically assigned by the daemon
32+
33+
**Format:** Network address (e.g., `localhost:9400`)
34+
35+
**Example:**
36+
37+
```bash
38+
export ENCORE_DEVDASH_LISTEN_ADDR=localhost:8080
39+
encore run
40+
```
41+
42+
### ENCORE_MCPSSE_LISTEN_ADDR
43+
44+
Overrides the listen address for the MCP SSE (Model Context Protocol Server-Sent Events) endpoint.
45+
46+
**Default:** Automatically assigned by the daemon
47+
48+
**Format:** Network address
49+
50+
**Example:**
51+
52+
```bash
53+
export ENCORE_MCPSSE_LISTEN_ADDR=localhost:9401
54+
```
55+
56+
### ENCORE_OBJECTSTORAGE_LISTEN_ADDR
57+
58+
Overrides the listen address for the object storage service endpoint.
59+
60+
**Default:** Automatically assigned by the daemon
61+
62+
**Format:** Network address
63+
64+
**Example:**
65+
66+
```bash
67+
export ENCORE_OBJECTSTORAGE_LISTEN_ADDR=localhost:9402
68+
```
69+
70+
## Advanced Development
71+
72+
These variables are primarily useful for advanced development scenarios, such as contributing to Encore itself or using custom builds.
73+
74+
### ENCORE_RUNTIMES_PATH
75+
76+
Specifies the path to the Encore runtimes directory.
77+
78+
**Default:** Auto-detected relative to the Encore installation (`<install_root>/runtimes`)
79+
80+
**Example:**
81+
82+
```bash
83+
export ENCORE_RUNTIMES_PATH=/path/to/custom/runtimes
84+
```
85+
86+
### ENCORE_GOROOT
87+
88+
Specifies the path to the custom Encore Go runtime.
89+
90+
**Default:** Auto-detected relative to the Encore installation (`<install_root>/encore-go`)
91+
92+
**Example:**
93+
94+
```bash
95+
export ENCORE_GOROOT=/path/to/custom/encore-go
96+
```
97+
98+
<Callout type="info">
99+
100+
For most users, these paths are automatically detected and don't need to be set. They are primarily useful when contributing to Encore or testing custom builds.
101+
102+
</Callout>

‎docs/menu.cue‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -385,6 +385,11 @@
385385
text: "Validation"
386386
path: "/go/develop/validation"
387387
file: "go/develop/validation"
388+
}, {
389+
kind: "basic"
390+
text: "Environment Variables"
391+
path: "/go/develop/env-vars"
392+
file: "go/develop/env-vars"
388393
}]
389394
},
390395
{
@@ -838,11 +843,16 @@
838843
text: "Multithreading"
839844
path: "/ts/develop/multithreading"
840845
file: "ts/develop/multithreading"
841-
},{
846+
}, {
842847
kind: "basic"
843848
text: "Running Scripts"
844849
path: "/ts/develop/running-scripts"
845850
file: "ts/develop/running-scripts"
851+
}, {
852+
kind: "basic"
853+
text: "Environment Variables"
854+
path: "/ts/develop/env-vars"
855+
file: "ts/develop/env-vars"
846856
}]
847857
},
848858
{

‎docs/ts/develop/env-vars.md‎

Lines changed: 215 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,215 @@
1+
---
2+
seotitle: Environment Variables Reference
3+
seodesc: Learn how to configure Encore's development environment using environment variables.
4+
title: Environment Variables
5+
subtitle: Configure your development environment
6+
lang: ts
7+
---
8+
9+
Encore works out of the box without configuration, but provides several environment variables for advanced use cases such as debugging, testing, or adapting Encore to specific workflow requirements.
10+
11+
## Daemon & Development Dashboard
12+
13+
These variables control how the Encore daemon operates and where it exposes its services.
14+
15+
### ENCORE_DAEMON_LOG_PATH
16+
17+
Controls the location of the Encore daemon log file.
18+
19+
**Default:** `<user_cache_dir>/encore/daemon.log`
20+
21+
**Example:**
22+
23+
```bash
24+
export ENCORE_DAEMON_LOG_PATH=/var/log/encore/daemon.log
25+
```
26+
27+
### ENCORE_DEVDASH_LISTEN_ADDR
28+
29+
Overrides the listen address for the local development dashboard.
30+
31+
**Default:** Automatically assigned by the daemon
32+
33+
**Format:** Network address (e.g., `localhost:9400`)
34+
35+
**Example:**
36+
37+
```bash
38+
export ENCORE_DEVDASH_LISTEN_ADDR=localhost:8080
39+
encore run
40+
```
41+
42+
### ENCORE_MCPSSE_LISTEN_ADDR
43+
44+
Overrides the listen address for the MCP SSE (Model Context Protocol Server-Sent Events) endpoint.
45+
46+
**Default:** Automatically assigned by the daemon
47+
48+
**Format:** Network address
49+
50+
**Example:**
51+
52+
```bash
53+
export ENCORE_MCPSSE_LISTEN_ADDR=localhost:9401
54+
```
55+
56+
### ENCORE_OBJECTSTORAGE_LISTEN_ADDR
57+
58+
Overrides the listen address for the object storage service endpoint.
59+
60+
**Default:** Automatically assigned by the daemon
61+
62+
**Format:** Network address
63+
64+
**Example:**
65+
66+
```bash
67+
export ENCORE_OBJECTSTORAGE_LISTEN_ADDR=localhost:9402
68+
```
69+
70+
## Logging Configuration
71+
72+
These variables control the logging behavior for TypeScript applications.
73+
74+
### ENCORE_RUNTIME_LOG
75+
76+
Sets the log level for Encore's internal runtime operations (written in Rust).
77+
78+
**Default:** `debug` (automatically set to `error` during `encore run`)
79+
80+
**Valid values:** `trace`, `debug`, `info`, `warn`, `error`
81+
82+
**Example:**
83+
84+
```bash
85+
# See detailed runtime logs
86+
export ENCORE_RUNTIME_LOG=trace
87+
encore run
88+
```
89+
90+
<Callout type="info">
91+
92+
If `RUST_LOG` is set, it takes precedence over `ENCORE_RUNTIME_LOG`. The runtime log controls logging for internal Encore modules.
93+
94+
</Callout>
95+
96+
### ENCORE_LOG
97+
98+
Sets the log level for your application code.
99+
100+
**Default:** `Trace` (log everything)
101+
102+
**Valid values:** `Off`, `Error`, `Warn`, `Info`, `Debug`, `Trace`
103+
104+
**Example:**
105+
106+
```typescript
107+
import log from "encore.dev/log";
108+
109+
log.info("This message respects ENCORE_LOG level");
110+
```
111+
112+
```bash
113+
# Only show errors and warnings
114+
export ENCORE_LOG=Warn
115+
encore run
116+
```
117+
118+
### ENCORE_NOLOG
119+
120+
Disables all logging when set to any non-empty value.
121+
122+
**Default:** Not set
123+
124+
**Example:**
125+
126+
```bash
127+
# Disable all logs
128+
export ENCORE_NOLOG=1
129+
encore run
130+
```
131+
132+
## Advanced Development
133+
134+
These variables are primarily useful for advanced development scenarios, such as contributing to Encore itself or using custom builds.
135+
136+
### ENCORE_RUNTIMES_PATH
137+
138+
Specifies the path to the Encore runtimes directory.
139+
140+
**Default:** Auto-detected relative to the Encore installation (`<install_root>/runtimes`)
141+
142+
**Example:**
143+
144+
```bash
145+
export ENCORE_RUNTIMES_PATH=/path/to/custom/runtimes
146+
```
147+
148+
### ENCORE_RUNTIME_LIB
149+
150+
Specifies the path to the native Node.js runtime library used by TypeScript applications.
151+
152+
**Default:** `<runtimes_path>/js/encore-runtime.node`
153+
154+
**Example:**
155+
156+
```bash
157+
export ENCORE_RUNTIME_LIB=/path/to/custom/encore-runtime.node
158+
```
159+
160+
### ENCORE_TSPARSER_PATH
161+
162+
Specifies the path to the TypeScript parser binary.
163+
164+
**Default:** Auto-detected from `encore` binary location or system `PATH`
165+
166+
**Example:**
167+
168+
```bash
169+
export ENCORE_TSPARSER_PATH=/path/to/custom/tsparser-encore
170+
```
171+
172+
<Callout type="info">
173+
174+
For most users, these paths are automatically detected and don't need to be set. They are primarily useful when contributing to Encore or testing custom builds.
175+
176+
</Callout>
177+
178+
## Debugging
179+
180+
### ENCORE_API_INCLUDE_INTERNAL_MESSAGE
181+
182+
Controls whether internal error messages are included in API error responses.
183+
184+
**Default:** automatically set to `1` during local development with `encore run`
185+
186+
**Format:** Any non-empty, non-"0" value is considered `true`
187+
188+
**Example:**
189+
190+
```bash
191+
# Manually enable for debugging
192+
export ENCORE_API_INCLUDE_INTERNAL_MESSAGE=1
193+
```
194+
195+
### RUST_LOG
196+
197+
Controls Rust-level logging for the Encore runtime. This provides more granular control than `ENCORE_RUNTIME_LOG`.
198+
199+
**Default:** Not set
200+
201+
**Format:** Standard Rust `env_logger` format (see [env_logger documentation](https://docs.rs/env_logger))
202+
203+
**Example:**
204+
205+
```bash
206+
# Enable info logs for all modules in the runtime
207+
export RUST_LOG=info
208+
encore run
209+
```
210+
211+
<Callout type="info">
212+
213+
`RUST_LOG` takes precedence over `ENCORE_RUNTIME_LOG`. Use `RUST_LOG` for fine-grained control over specific runtime modules.
214+
215+
</Callout>

0 commit comments

Comments
 (0)