Self-Hosting Guide

This guide covers how to self-host the EnvLink server and optionally contribute to CLI development.

Prerequisites

Before you begin, ensure you have the following installed:

Node.js >= 18.0.0
Bun (for server) - Install Bun
MongoDB (local or cloud instance)
Git

Part 1: Server Setup

1. Clone Repository

git clone https://github.com/AbabilCore/envlink.git
cd envlink/server

2. Install Dependencies

bun install

3. MongoDB Setup

Option A: MongoDB Atlas (Cloud - Recommended)

Create account at mongodb.com/cloud/atlas
Create a free cluster
Get connection string
Use it in your.envfile

Option B: Local MongoDB

# Ubuntu/Debian
sudo apt-get install mongodb

# macOS
brew install mongodb-community

# Start MongoDB
sudo systemctl start mongodb
brew services start mongodb-community

Connection string:mongodb://localhost:27017/envlink

4. Environment Configuration

Copy.env.exampleto.env:

cp .env.example .env

Edit.envwith your configuration:

PORT=8000
DB_URI=mongodb://localhost:27017/envlink
PROD_SITE_URL=https://your-domain.com
CRON_SECRET=your-random-secret-token

5. Start Server

Development:

bun run dev

Server runs at: http://localhost:8000

Production:

bun run build
bun run start

Preview (test production build locally):

bun run preview

6. Server Scripts Reference

bun run dev- Development mode with hot reload
bun run build- Build for production
bun run preview- Preview production build locally
bun run start- Run production build
bun run test:api- Run API test suite

7. Deployment Options

VPS Deployment (Most Control)

Setup Server
- Ubuntu 20.04+ or similar
- Install Node.js, Bun, MongoDB (or use MongoDB Atlas)
- Configure firewall to allow port 8000

Clone and Setup

git clone https://github.com/AbabilCore/envlink.git
cd envlink/server
bun install
cp .env.example .env

Configure Environment
- Edit.envfile
- Set your domain and MongoDB URI

Process Manager (PM2)

npm install -g pm2
pm2 start scripts/app.sh --name envlink-server --interpreter bash -- start
pm2 save
pm2 startup

Reverse Proxy (Nginx)

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:8000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

SSL with Certbot
```
sudo certbot --nginx -d your-domain.com
```

Cloud Platforms (Render / Railway)

Connect your GitHub repository
Set root directory:./
Set build command:cd server && bun install && bun run build
Set start command:cd server && bun run start
Add environment variables:
- PORT=8000
- DB_URI=<your-mongodb-uri>
- PROD_SITE_URL=<your-url>
- CRON_SECRET=<optional-secret>

8. Cron Job Setup

Set up automatic cleanup of expired EnvLinks:

Without Protection:

curl https://your-domain.com/api/envlinks/cron/cleanup

With Protection (Recommended):

IfCRON_SECRETis set in.env, configure cron with the header:

Linux Cron:

crontab -e

Add this line (runs every hour):

0 * * * * curl -H "X-Cron-Secret: your-random-secret-token" https://your-domain.com/api/envlinks/cron/cleanup

EasyCron / Cron-job.org:

URL:https://your-domain.com/api/envlinks/cron/cleanup
Method:GET
Headers:X-Cron-Secret: your-random-secret-token
Schedule: Every hour

Render / Railway Cron:

Command:curl -H "X-Cron-Secret: $CRON_SECRET" https://your-domain.com/api/envlinks/cron/cleanup
Schedule:0 * * * *

9. Test Your Server

cd server
bun run test:api

For more server details, see the server README.

Part 2: CLI Development (Optional)

Want to contribute to or modify the CLI? Here's how:

1. Setup CLI Development

From the repository root:

npm install

2. Development Mode

npm run dev

3. Local Testing

Test commands without building or linking:

npm run dev -- create
npm run dev -- install <id>
npm run dev -- info <id>
npm run dev -- update <id>
npm run dev -- expire <id>

Or use the automated test suite:

npm run test:cli

4. CLI Scripts Reference

npm run dev- Development mode with watch
npm run test- Run CLI directly in interactive mode
npm run test:cli- Run automated test suite with Vitest
npm run build- Build for production
npm start- Run built version

5. Build CLI

npm run build

6. Test Built Version

npm link
envlink create

7. Publishing Your Own CLI (Scoped Package)

Want to publish your modified version? Publish as a scoped package:

Update package.json

{
  "name": "@your-username/envlink",
  "version": "1.0.0",
  "description": "Your custom EnvLink CLI"
}

Configure Your API Endpoint

Update src/config/index.ts:

const ENV = {
  IS_DEV: process.env.NODE_ENV === "development",
  get API_URL() {
    return this.IS_DEV
      ? "http://localhost:8000/api"
      : "https://your-domain.com/api"; // your production api URL
  },
};

Build and Publish

npm run build
npm login
npm publish --access public

Users Install Your CLI

npm install -g @your-username/envlink
npx @your-username/envlink create

Code Quality

The project uses Biome for linting:

npx biome check .
npx biome check --apply .

Repository Structure

This repository contains both the CLI tool and the web server:

CLI Tool (root): The EnvLink command-line interface
Web Server /server: Documentation website and API server

Contributing

Fork the repository
Create a feature branch
Make your changes
Test thoroughly (both CLI and server if applicable)
Commit with clear messages
Push to your fork
Open a Pull Request

License

MIT License - see LICENSE file for details.