Skip to content

Commit 4fb1b51

Browse files
mohitgauniyalmohitgauniyal
committed
docs: split deployment and terminal usage into docs/ folder, trim README
1 parent 82bd996 commit 4fb1b51

File tree

5 files changed

+238
-160
lines changed

5 files changed

+238
-160
lines changed

‎.dockerignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,4 @@ __tests__
1616
.github
1717
tests/
1818
.github/
19+
docs/

‎.npmignore‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -13,3 +13,4 @@ server/db.sqlite
1313
assets/
1414
tests/
1515
.github/
16+
docs/

‎README.md‎

Lines changed: 4 additions & 160 deletions
Original file line numberDiff line numberDiff line change
@@ -102,147 +102,19 @@ For teams who want auth, custom retention, or branding — create `instbyte.conf
102102

103103
Then run `npx instbyte` in the same directory. The config is picked up automatically.
104104

105-
### Keeping It Running
106-
For persistent team use, run it as a background process:
107-
108-
```bash
109-
# using pm2
110-
npm install -g pm2
111-
pm2 start "npx instbyte" --name instbyte
112-
pm2 save
113-
```
114-
115-
Or use any process manager you already have — systemd, screen, tmux.
105+
For persistent deployment options including pm2, systemd, and Docker, see the [Deployment Guide](docs/deployment.md).
116106

117107
---
118108

119109
## Docker
120110

121-
The fastest way to run Instbyte with Docker:
122-
```bash
123-
docker compose up -d
124-
```
125-
126-
Or with plain Docker:
127-
```bash
128-
docker run -d \
129-
-p 3000:3000 \
130-
-v $(pwd)/instbyte-data:/data \
131-
-e INSTBYTE_DATA=/data \
132-
-e INSTBYTE_UPLOADS=/data/uploads \
133-
--name instbyte \
134-
mohitgauniyal/instbyte
135-
```
136-
137-
Data persists in `./instbyte-data` on your host. The same folder used by `npx instbyte` — so switching between the two preserves all your data.
138-
139-
### With a config file
140-
141-
Mount your config file into the container:
142-
```yaml
143-
services:
144-
instbyte:
145-
image: mohitgauniyal/instbyte
146-
ports:
147-
- "3000:3000"
148-
volumes:
149-
- ./instbyte-data:/data
150-
- ./instbyte.config.json:/app/instbyte.config.json
151-
environment:
152-
- INSTBYTE_DATA=/data
153-
- INSTBYTE_UPLOADS=/data/uploads
154-
restart: unless-stopped
155-
```
156-
157-
### Changing the port
158-
159-
Edit the host port in `docker-compose.yml`:
160-
```yaml
161-
ports:
162-
- "8080:3000" # now runs on port 8080
163-
```
164-
165-
> **Note:** File uploads may not work correctly on Windows Docker Desktop due to network limitations. For Windows, use `npx instbyte` directly or deploy on a Linux server.
111+
For Docker setup, persistent data, and config file mounting, see [Deployment Guide](docs/deployment.md).
166112

167113
---
168114

169115
## Reverse Proxy
170116

171-
For teams who want to access Instbyte over HTTPS or from outside their local network, running it behind a reverse proxy is the standard approach.
172-
173-
> **Important:** Instbyte uses WebSockets for real-time sync. Your proxy must be configured to forward WebSocket connections — otherwise the app will load but live updates will stop working.
174-
175-
### Nginx
176-
```nginx
177-
server {
178-
listen 80;
179-
server_name instbyte.yourdomain.com;
180-
181-
# Redirect HTTP to HTTPS
182-
return 301 https://$host$request_uri;
183-
}
184-
185-
server {
186-
listen 443 ssl;
187-
server_name instbyte.yourdomain.com;
188-
189-
ssl_certificate /etc/letsencrypt/live/instbyte.yourdomain.com/fullchain.pem;
190-
ssl_certificate_key /etc/letsencrypt/live/instbyte.yourdomain.com/privkey.pem;
191-
192-
# Increase max upload size to match Instbyte's limit
193-
client_max_body_size 2G;
194-
195-
location / {
196-
proxy_pass http://localhost:3000;
197-
proxy_http_version 1.1;
198-
199-
# Required for WebSocket support
200-
proxy_set_header Upgrade $http_upgrade;
201-
proxy_set_header Connection "upgrade";
202-
203-
proxy_set_header Host $host;
204-
proxy_set_header X-Real-IP $remote_addr;
205-
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
206-
proxy_set_header X-Forwarded-Proto $scheme;
207-
208-
# Prevent proxy timeouts on large uploads
209-
proxy_read_timeout 300s;
210-
proxy_send_timeout 300s;
211-
}
212-
}
213-
```
214-
215-
Get a free SSL certificate with Certbot:
216-
```bash
217-
certbot --nginx -d instbyte.yourdomain.com
218-
```
219-
220-
### Caddy
221-
222-
Caddy automatically handles HTTPS certificates — no Certbot needed.
223-
```caddy
224-
instbyte.yourdomain.com {
225-
reverse_proxy localhost:3000
226-
}
227-
```
228-
229-
Caddy handles WebSocket forwarding and HTTPS automatically. That's all you need.
230-
231-
### With Docker
232-
233-
If running Instbyte via Docker, proxy to the mapped host port:
234-
```nginx
235-
proxy_pass http://localhost:3000;
236-
```
237-
238-
Or use Docker's internal network — replace `localhost` with the container name:
239-
```nginx
240-
proxy_pass http://instbyte:3000;
241-
```
242-
243-
### Keeping it LAN-only
244-
245-
If you don't want external access but still want HTTPS on your local network, tools like [Tailscale](https://tailscale.com) or [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) are good options that require no open ports.
117+
For Nginx, Caddy, and HTTPS setup, see [Deployment Guide](docs/deployment.md).
246118

247119
---
248120

@@ -439,35 +311,7 @@ node server/server.js
439311

440312
## Terminal Usage
441313

442-
Since Instbyte exposes a simple HTTP API, you can push content directly from your terminal using `curl` — no browser needed.
443-
444-
**Send a log file:**
445-
```bash
446-
curl -X POST http://192.168.x.x:3000/text \
447-
-H "Content-Type: application/json" \
448-
-d "{\"content\": \"$(cat error.log)\", \"channel\": \"general\", \"uploader\": \"terminal\"}"
449-
```
450-
451-
**Pipe command output directly:**
452-
```bash
453-
npm run build 2>&1 | curl -X POST http://192.168.x.x:3000/text \
454-
-H "Content-Type: application/json" \
455-
--data-binary @- \
456-
-H "X-Channel: general" \
457-
-H "X-Uploader: CI"
458-
```
459-
460-
**Upload a file from the terminal:**
461-
```bash
462-
curl -X POST http://192.168.x.x:3000/upload \
463-
-F "file=@./build.log" \
464-
-F "channel=general" \
465-
-F "uploader=terminal"
466-
```
467-
468-
Replace `192.168.x.x:3000` with the URL shown when Instbyte starts. If auth is enabled, add `-b "instbyte_auth=your-token"` to each request.
469-
470-
Useful for piping stack traces, build logs, or environment dumps straight into a channel your whole team can see instantly.
314+
Push content from your terminal using curl — no browser needed. See [Terminal Usage Guide](docs/terminal-usage.md).
471315

472316
---
473317

‎docs/deployment.md‎

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
# Deployment Guide
2+
3+
## Keeping It Running
4+
5+
For persistent team use, run Instbyte as a background process so it survives terminal closes and reboots.
6+
7+
### pm2
8+
```bash
9+
npm install -g pm2
10+
pm2 start "npx instbyte" --name instbyte
11+
pm2 save
12+
pm2 startup # generates a command to run — copy and run it to enable boot start
13+
```
14+
15+
### systemd (Linux)
16+
Create `/etc/systemd/system/instbyte.service`:
17+
```ini
18+
[Unit]
19+
Description=Instbyte
20+
After=network.target
21+
22+
[Service]
23+
Type=simple
24+
User=youruser
25+
WorkingDirectory=/home/youruser/instbyte
26+
ExecStart=npx instbyte
27+
Restart=on-failure
28+
29+
[Install]
30+
WantedBy=multi-user.target
31+
```
32+
33+
Then enable it:
34+
```bash
35+
sudo systemctl daemon-reload
36+
sudo systemctl enable instbyte
37+
sudo systemctl start instbyte
38+
```
39+
40+
### screen / tmux
41+
```bash
42+
screen -S instbyte
43+
npx instbyte
44+
# Ctrl+A then D to detach
45+
```
46+
47+
---
48+
49+
## Docker
50+
51+
The fastest way to run Instbyte with Docker:
52+
```bash
53+
docker compose up -d
54+
```
55+
56+
Or with plain Docker:
57+
```bash
58+
docker run -d \
59+
-p 3000:3000 \
60+
-v $(pwd)/instbyte-data:/data \
61+
-e INSTBYTE_DATA=/data \
62+
-e INSTBYTE_UPLOADS=/data/uploads \
63+
--name instbyte \
64+
mohitgauniyal/instbyte
65+
```
66+
67+
Data persists in `./instbyte-data` on your host. The same folder used by `npx instbyte` — so switching between the two preserves all your data.
68+
69+
### With a config file
70+
71+
Mount your config file into the container:
72+
```yaml
73+
services:
74+
instbyte:
75+
image: mohitgauniyal/instbyte
76+
ports:
77+
- "3000:3000"
78+
volumes:
79+
- ./instbyte-data:/data
80+
- ./instbyte.config.json:/app/instbyte.config.json
81+
environment:
82+
- INSTBYTE_DATA=/data
83+
- INSTBYTE_UPLOADS=/data/uploads
84+
restart: unless-stopped
85+
```
86+
87+
### Changing the port
88+
89+
Edit the host port in `docker-compose.yml`:
90+
```yaml
91+
ports:
92+
- "8080:3000" # now runs on port 8080
93+
```
94+
95+
> **Note:** File uploads may not work correctly on Windows Docker Desktop due to network limitations. For Windows, use `npx instbyte` directly or deploy on a Linux server.
96+
97+
---
98+
99+
## Reverse Proxy
100+
101+
For teams who want to access Instbyte over HTTPS or from outside their local network, running it behind a reverse proxy is the standard approach.
102+
103+
> **Important:** Instbyte uses WebSockets for real-time sync. Your proxy must be configured to forward WebSocket connections — otherwise the app will load but live updates will stop working.
104+
105+
### Nginx
106+
```nginx
107+
server {
108+
listen 80;
109+
server_name instbyte.yourdomain.com;
110+
111+
# Redirect HTTP to HTTPS
112+
return 301 https://$host$request_uri;
113+
}
114+
115+
server {
116+
listen 443 ssl;
117+
server_name instbyte.yourdomain.com;
118+
119+
ssl_certificate /etc/letsencrypt/live/instbyte.yourdomain.com/fullchain.pem;
120+
ssl_certificate_key /etc/letsencrypt/live/instbyte.yourdomain.com/privkey.pem;
121+
122+
# Increase max upload size to match Instbyte's limit
123+
client_max_body_size 2G;
124+
125+
location / {
126+
proxy_pass http://localhost:3000;
127+
proxy_http_version 1.1;
128+
129+
# Required for WebSocket support
130+
proxy_set_header Upgrade $http_upgrade;
131+
proxy_set_header Connection "upgrade";
132+
133+
proxy_set_header Host $host;
134+
proxy_set_header X-Real-IP $remote_addr;
135+
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
136+
proxy_set_header X-Forwarded-Proto $scheme;
137+
138+
# Prevent proxy timeouts on large uploads
139+
proxy_read_timeout 300s;
140+
proxy_send_timeout 300s;
141+
}
142+
}
143+
```
144+
145+
Get a free SSL certificate with Certbot:
146+
```bash
147+
certbot --nginx -d instbyte.yourdomain.com
148+
```
149+
150+
### Caddy
151+
152+
Caddy automatically handles HTTPS certificates — no Certbot needed.
153+
```caddy
154+
instbyte.yourdomain.com {
155+
reverse_proxy localhost:3000
156+
}
157+
```
158+
159+
Caddy handles WebSocket forwarding and HTTPS automatically. That's all you need.
160+
161+
### With Docker
162+
163+
If running Instbyte via Docker, proxy to the mapped host port:
164+
```nginx
165+
proxy_pass http://localhost:3000;
166+
```
167+
168+
Or use Docker's internal network — replace `localhost` with the container name:
169+
```nginx
170+
proxy_pass http://instbyte:3000;
171+
```
172+
173+
### Keeping it LAN-only
174+
175+
If you don't want external access but still want HTTPS on your local network, tools like [Tailscale](https://tailscale.com) or [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) are good options that require no open ports.

0 commit comments

Comments
 (0)
⚡