# How to Set Up Environment Variables in .env File for Content Paths and Server Configuration in Astro Big Doc

> Learn to set up environment variables in your .env file for content paths and server configuration in Astro Big Doc Customize CONTENT OUT_DIR HOST and PORT for your project

- Repository: [Micro Web Stacks/astro-big-doc](https://github.com/microwebstacks/astro-big-doc)
- Tags: how-to-guide
- Published: 2026-03-07

---

**Create a `.env` file in the project root using `.env.example` as a template, then define variables like `CONTENT`, `OUT_DIR`, `HOST`, and `PORT` to customize content paths and server behavior in the astro-big-doc project.**

The astro-big-doc repository relies on environment variables to control everything from markdown source locations to TLS certificate paths. Learning how to set up environment variables in .env file for content paths and server configuration ensures your documentation site builds correctly across development and production environments.

## Essential Environment Variables Reference

The project reads configuration from `process.env` across several core modules. All variables are optional and provide sensible defaults when omitted.

### Build and Output Paths

| Variable | Default | Purpose | Source File |
|----------|---------|---------|-------------|
| `OUT_DIR` | `dist` | Directory where the static site is emitted | `server/server.js:L13` |
| `PUBLIC_BASE` | `""` | Base path when deployed under a sub-directory (e.g., `/docs`) | `config.js:L8` |
| `STRUCTURE` | `<repo-root>/.structure` | Path to the generated `.structure` folder | `config.js:L10` |
| `CONTENT` | `<repo-root>/content` | Root directory for markdown and assets | `config.js:L11` |

### Server Configuration

| Variable | Default | Purpose | Source File |
|----------|---------|---------|-------------|
| `PROTOCOL` | `http` | HTTP or HTTPS protocol for the server URL | `server/server.js:L14` |
| `HOST` | `0.0.0.0` | Host address the server binds to | `server/server.js:L15` |
| `PORT` | `3001` | Port number for the server | `server/server.js:L16` |
| `ENABLE_CORS` | `false` | Enables CORS headers when set to `"true"` | `server/server.js:L19` |

### Authentication and Security

| Variable | Default | Purpose | Source File |
|----------|---------|---------|-------------|
| `ENABLE_AUTH` | `false` | Turns on GitHub OAuth when set to `"true"` | `server/server.js:L24` |
| `GITHUB_CLIENT_ID` | `undefined` | OAuth client ID for GitHub login | `server/auth/auth_router.js:L15` |
| `GITHUB_CLIENT_SECRET` | `undefined` | OAuth client secret for GitHub login | `server/auth/auth_router.js:L16` |
| `SESSION_SECRET` | `undefined` | Secret used to sign the session cookie | `server/auth/auth_router.js:L29` |
| `KEY_FILE` | `undefined` | Path to TLS private key (used with auth) | `server/server.js:L39` |
| `CERT_FILE` | `undefined` | Path to TLS certificate (used with auth) | `server/server.js:L40` |

### External Services

| Variable | Default | Purpose | Source File |
|----------|---------|---------|-------------|
| `KROKI_SERVER` | `https://kroki.io` | URL of the external Kroki diagram rendering service | `config.js:L12` |

## Step-by-Step .env Configuration

The project uses the `dotenv` package to load variables automatically when you run `npm run dev` or `npm start`. Create a file named `.env` in the project root (sibling to `.env.example`) and populate it based on your environment.

### Local Development Setup

For local development, you typically only need to customize server ports and content paths if the defaults conflict with existing services.

```text

# Server configuration

HOST=0.0.0.0
PORT=3001
PROTOCOL=http

# Content paths (optional - shown with defaults)

CONTENT=content
STRUCTURE=.structure
OUT_DIR=dist
PUBLIC_BASE=

# Disable optional features for local dev

ENABLE_CORS=false
ENABLE_AUTH=false

```

### Production Configuration with GitHub OAuth

When deploying to production with GitHub OAuth enabled, you must provide TLS certificates and OAuth credentials.

```text

# Server binding

HOST=0.0.0.0
PORT=443
PROTOCOL=https

# Build output

OUT_DIR=dist
PUBLIC_BASE=/big-doc

# Content source

CONTENT=/var/www/content
STRUCTURE=/var/www/.structure

# Security

ENABLE_CORS=true
ENABLE_AUTH=true
SESSION_SECRET=your-random-256-bit-secret-string
GITHUB_CLIENT_ID=Iv1.xxxxxxxxxxxxxxxx
GITHUB_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# TLS certificates (required when ENABLE_AUTH=true)

KEY_FILE=/etc/ssl/private/myserver.key
CERT_FILE=/etc/ssl/certs/myserver.crt

# External services

KROKI_SERVER=https://kroki.mycompany.com

```

> **Security Warning:** Never commit the real `.env` file to version control. The repository includes `.env.example` as a template, but your actual secrets should remain local or in your deployment platform's secret manager.

## Where Environment Variables Are Consumed in the Source Code

Understanding which modules read these variables helps with debugging and customization.

### Central Configuration ([`config.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/config.js))

The [`config.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/config.js) file at the repository root resolves content-related paths and public base settings. It is imported by both the client-side entry point ([`client_config.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/client_config.js)) and the server bootstrap to ensure consistent path resolution across the stack.

- `PUBLIC_BASE` (line 8): Sets the base path for deployments under sub-directories.
- `STRUCTURE` (line 10): Defines the generated structure folder path.
- `CONTENT` (line 11): Specifies the root directory for markdown content and assets.
- `KROKI_SERVER` (line 12): Configures the external diagram rendering service URL.

### Server Bootstrap ([`server/server.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/server/server.js))

The server initialization logic reads network and security settings directly from `process.env` during startup:

- Lines 13-16: `OUT_DIR`, `PROTOCOL`, `HOST`, and `PORT` define the server binding and static file serving location.
- Line 19: `ENABLE_CORS` controls Cross-Origin Resource Sharing headers.
- Line 24: `ENABLE_AUTH` toggles the GitHub OAuth authentication flow.
- Lines 39-40: `KEY_FILE` and `CERT_FILE` provide TLS certificate paths when authentication is enabled.

### Authentication Router ([`server/auth/auth_router.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/server/auth/auth_router.js))

When `ENABLE_AUTH` is set to `"true"`, the authentication module initializes GitHub OAuth and session management:

- Lines 15-16: `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET` configure the OAuth application credentials.
- Line 29: `SESSION_SECRET` signs the encrypted session cookies to prevent tampering.

### Client Configuration ([`client_config.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/client_config.js))

This entry point imports the central [`config.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/config.js) to ensure the client-side code respects `PUBLIC_BASE` when generating links and loading assets, maintaining consistency with the server-side rendering.

## Summary

- **Environment variables** in astro-big-doc control content paths (`CONTENT`, `STRUCTURE`), build output (`OUT_DIR`), server binding (`HOST`, `PORT`, `PROTOCOL`), and security features (`ENABLE_AUTH`, `GITHUB_CLIENT_ID`).
- **Configuration is centralized** in [`config.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/config.js) for paths and [`server/server.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/server/server.js) for network settings, with authentication logic isolated in [`server/auth/auth_router.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/server/auth/auth_router.js).
- **Setup requires** creating a `.env` file in the project root using `.env.example` as a template; the `dotenv` package loads these automatically when running `npm run dev` or `npm start`.
- **Security best practices** include never committing `.env` to version control and using strong, random values for `SESSION_SECRET` in production.

## Frequently Asked Questions

### What happens if I don't create a .env file?

If you do not create a `.env` file, the application falls back to sensible defaults defined in the source code. For example, `CONTENT` defaults to `<repo-root>/content`, `PORT` defaults to `3001`, and `ENABLE_AUTH` defaults to `false`. However, for production deployments or custom content locations, you must explicitly define these variables in your `.env` file.

### Do I need to manually load the .env file in my code?

No manual loading is required. The project uses the `dotenv` package invoked via `dotenv/config` in the startup scripts. When you run `npm run dev` or `npm start`, the environment variables are automatically injected into `process.env` before any application code executes, including the configuration modules [`config.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/config.js) and [`server/server.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/server/server.js).

### Which variables are required for enabling GitHub authentication?

To enable GitHub OAuth, you must set `ENABLE_AUTH=true` and provide `GITHUB_CLIENT_ID`, `GITHUB_CLIENT_SECRET`, and `SESSION_SECRET`. Additionally, because the authentication flow requires secure cookies, you must enable HTTPS by setting `PROTOCOL=https` and providing `KEY_FILE` and `CERT_FILE` paths to your TLS certificates. These are read from [`server/auth/auth_router.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/server/auth/auth_router.js) (lines 15-16 and 29) and [`server/server.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/server/server.js) (lines 24, 39-40).

### Can I deploy the site under a sub-directory using environment variables?

Yes. Set the `PUBLIC_BASE` variable to your sub-directory path, such as `PUBLIC_BASE=/docs`. This value is consumed by [`config.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/config.js) at line 8 and propagated to both the client configuration ([`client_config.js`](https://github.com/microwebstacks/astro-big-doc/blob/main/client_config.js)) and the server, ensuring all internal links and asset paths are prefixed correctly for sub-directory deployments.