bindler 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,142 @@
+# bindler
+
+cli for managing multiple projects behind cloudflare tunnel with nginx and pm2.
+
+## install
+
+```bash
+npm install -g bindler
+```
+
+you'll also need:
+- node.js 18+
+- nginx - `brew install nginx` (mac) or `apt install nginx` (linux)
+- pm2 - `npm install -g pm2`
+- cloudflared (optional) - `brew install cloudflared` or see https://pkg.cloudflare.com
+
+run `bindler setup` to install missing dependencies automatically.
+
+## usage
+
+```bash
+# check your system
+bindler doctor
+
+# create a project (interactive)
+bindler new
+
+# or with flags
+bindler new --name mysite --hostname mysite.local --local
+bindler new --name api --type npm --hostname api.example.com --start "npm start"
+
+# apply nginx config
+bindler apply
+
+# start npm apps
+bindler start myapp
+
+# check status
+bindler status
+```
+
+## commands
+
+**projects:** `new`, `list`, `status`, `update <name>`, `edit <name>`, `remove <name>`
+
+**processes:** `start <name>`, `stop <name>`, `restart <name>`, `logs <name>`
+
+**system:** `apply`, `doctor`, `ports`, `info`, `check <hostname>`, `setup`
+
+use `--all` with start/stop/restart to manage all npm projects at once.
+
+## local development
+
+for local-only projects (no cloudflare), use the `--local` flag:
+
+```bash
+bindler new --local
+```
+
+then add the hostname to /etc/hosts:
+```bash
+echo "127.0.0.1  myapp.local" | sudo tee -a /etc/hosts
+```
+
+access at `http://myapp.local:8080`
+
+## vps / direct mode
+
+if you have a vps and don't need cloudflare tunnel, use direct mode:
+
+```bash
+bindler setup --direct
+```
+
+this will:
+- set nginx to listen on port 80 directly
+- skip cloudflare dns routing
+- optionally set up ssl with let's encrypt (certbot)
+
+your projects will be accessible at `https://app.yourdomain.com` (no port needed).
+
+```bash
+# add a project
+bindler new --name myapp --hostname app.yourdomain.com
+
+# apply config + get ssl certificate
+sudo bindler apply
+```
+
+## how it works
+
+**tunnel mode** (default):
+```
+internet -> cloudflare -> cloudflared tunnel -> nginx (:8080) -> your projects
+```
+
+**direct mode** (vps):
+```
+internet -> nginx (:80/:443) -> your projects
+```
+
+nginx routes by hostname. static sites serve files directly, npm apps run via pm2 and get proxied.
+
+## config
+
+stored in `~/.config/bindler/config.json`
+
+```json
+{
+  "defaults": {
+    "nginxListen": "127.0.0.1:8080",
+    "tunnelName": "homelab"
+  },
+  "projects": []
+}
+```
+
+## cloudflare tunnel setup
+
+```bash
+cloudflared tunnel login
+cloudflared tunnel create homelab
+```
+
+create `~/.cloudflared/config.yml`:
+```yaml
+tunnel: homelab
+credentials-file: ~/.cloudflared/<tunnel-id>.json
+ingress:
+  - service: http://localhost:8080
+```
+
+run it:
+```bash
+cloudflared tunnel run homelab
+```
+
+bindler will auto-create dns routes when you run `bindler apply`.
+
+## license
+
+mit