Skip to main content
Shipyard is configured entirely through environment variables. Create a .env file in the project root before starting the server — the application reads it on startup via dotenv. All variables listed below are required; the server will behave incorrectly or fail to start if any are missing.
Never commit your .env file to version control. Add it to your .gitignore before your first commit. It contains secrets that grant access to your database, GitHub account, and encrypted project data.

​
Database

​
string
required
PostgreSQL connection string. Shipyard uses this to connect to the database through pg and Drizzle ORM.

​
GitHub OAuth

Shipyard uses GitHub OAuth for user authentication. You obtain these values when you create an OAuth App in your GitHub account under Settings → Developer Settings → OAuth Apps.
​
string
required
The client ID from your GitHub OAuth App. Shipyard includes this in the authorization URL it redirects users to when they sign in.
​
string
required
The client secret from your GitHub OAuth App. Shipyard sends this to GitHub during the token exchange step of the OAuth flow. Keep this value confidential — treat it like a password.

​
Authentication and encryption

​
string
required
Secret used to sign JWT session tokens. Shipyard issues a JWT after a successful GitHub OAuth login and verifies it on every authenticated API request. Use a long, random string — this value should never be guessable.
​
string
required
A 32-byte key encoded as a 64-character hex string, used for AES-256-GCM encryption of project secrets. Shipyard encrypts environment variables before storing them in the database and decrypts them only at build time — they are never returned in API responses.Generate a secure key with:
​
string
required
Secret used to verify the HMAC-SHA256 signature on incoming GitHub webhook payloads. When you connect a repository, Shipyard registers this secret with GitHub. On each push event, Shipyard recomputes the signature using this value and compares it with the X-Hub-Signature-256 header using a timing-safe comparison to prevent brute-force attacks.

​
Routing and URLs

​
string
required
The base domain used for subdomain routing of deployed projects. When a project named my-app is deployed, it is served at my-app.<BASE_DOMAIN>.For local development, use lvh.me:8080 — lvh.me is a public DNS entry that resolves all subdomains to 127.0.0.1, so my-app.lvh.me:8080 reaches your local Shipyard server without any extra configuration.
On a VPS, set this to your actual domain (e.g., useshipyard.xyz).
​
string
required
The URL of your frontend application. Shipyard uses this value in two places:
  • CORS: only requests from this origin are permitted
  • OAuth redirect: after GitHub OAuth completes, Shipyard redirects the user back to this URL with the JWT token appended
​
string
required
The public URL where GitHub sends webhook events. When you connect a repository, Shipyard registers this URL as the webhook endpoint via the GitHub API. It must be publicly reachable — GitHub cannot send events to localhost.
During local development, use a tunneling tool to expose port 8080 and use the tunnel URL here. Update this value and restart the server whenever your tunnel URL changes.

​
Full example

A complete .env for local development: