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

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.

# 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.

# 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)

The 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) 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)

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)

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)

This entry point imports the central 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 for paths and server/server.js for network settings, with authentication logic isolated in 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 and 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 (lines 15-16 and 29) and 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 at line 8 and propagated to both the client configuration (client_config.js) and the server, ensuring all internal links and asset paths are prefixed correctly for sub-directory deployments.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}