Skip to content

Commit bfca216

Browse files
chrisbbreuerchrisbbreuer
committed
docs: add features & advanced sections
1 parent dd4cbdd commit bfca216

15 files changed

+1630
-3
lines changed

‎docs/.vitepress/config.ts‎

Lines changed: 21 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,7 +59,27 @@ const sidebar = [
5959
{ text: 'Config', link: '/config' },
6060
],
6161
},
62-
{ text: 'Showcase', link: '/Showcase' },
62+
{ text: 'Showcase', link: '/showcase' },
63+
{
64+
text: 'Features',
65+
items: [
66+
{ text: 'Custom Domains', link: '/features/custom-domains' },
67+
{ text: 'HTTPS Support', link: '/features/https-support' },
68+
{ text: 'Hosts Management', link: '/features/hosts-management' },
69+
{ text: 'Bun Plugin', link: '/features/bun-plugin' },
70+
{ text: 'Multiple Proxies', link: '/features/multiple-proxies' },
71+
],
72+
},
73+
{
74+
text: 'Advanced',
75+
items: [
76+
{ text: 'SSL Configuration', link: '/advanced/ssl-configuration' },
77+
{ text: 'Custom Certificates', link: '/advanced/custom-certificates' },
78+
{ text: 'Cleanup Strategies', link: '/advanced/cleanup-strategies' },
79+
{ text: 'Frameworks Integration', link: '/advanced/frameworks-integration' },
80+
],
81+
},
82+
{ text: 'API Reference', link: '/api-reference' },
6383
]
6484
const description = 'A modern, fast reverse proxy. For a better local development environment.'
6585
const title = 'rpx | A modern, fast reverse proxy. For a better local development environment.'

‎docs/advanced/cleanup-strategies.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
# Cleanup Strategies
2+
3+
rpx creates various resources like hosts file entries and SSL certificates. Understanding and configuring how these resources are cleaned up is important for maintaining a tidy development environment.
4+
5+
## Default Behavior
6+
7+
By default:
8+
9+
- Hosts file entries are added but not automatically removed
10+
- SSL certificates are generated and kept for reuse
11+
- Process cleanup happens when rpx is terminated with Ctrl+C or when the process ends
12+
13+
## Configuring Cleanup
14+
15+
You can configure cleanup behavior in several ways:
16+
17+
### Library Configuration
18+
19+
```ts
20+
import { startProxy } from '@stacksjs/rpx'
21+
22+
startProxy({
23+
from: 'localhost:3000',
24+
to: 'myapp.test',
25+
cleanup: {
26+
hosts: true, // Clean up hosts file entries on exit
27+
certs: false // Keep certificates for future use
28+
}
29+
})
30+
```
31+
32+
### CLI Configuration
33+
34+
```bash
35+
# Enable hosts cleanup
36+
rpx --from localhost:3000 --to myapp.test --cleanup
37+
38+
# Specify which resources to clean up (future version)
39+
rpx --from localhost:3000 --to myapp.test --cleanup-hosts --no-cleanup-certs
40+
```
41+
42+
### Bun Plugin
43+
44+
The Bun plugin automatically handles cleanup when the server is stopped:
45+
46+
```ts
47+
import rpxPlugin from 'bun-plugin-rpx'
48+
49+
export default {
50+
plugins: [
51+
rpxPlugin({
52+
domain: 'myapp.test'
53+
// Cleanup is handled automatically
54+
})
55+
]
56+
}
57+
```
58+
59+
## Signal Handling
60+
61+
rpx handles the following signals for cleanup:
62+
63+
- `SIGINT` (Ctrl+C)
64+
- `SIGTERM` (process termination)
65+
- Uncaught exceptions
66+
67+
When these signals are received, rpx will:
68+
69+
1. Stop any watched processes it started
70+
2. Close all proxy servers
71+
3. Clean up hosts file entries (if configured)
72+
4. Clean up certificates (if configured)
73+
74+
## Manual Cleanup
75+
76+
You can manually clean up resources:
77+
78+
```ts
79+
import { cleanup } from '@stacksjs/rpx'
80+
81+
// Clean up everything
82+
cleanup({
83+
hosts: true,
84+
certs: true,
85+
domains: ['myapp.test', 'api.myapp.test'],
86+
verbose: true
87+
})
88+
```
89+
90+
## Cleanup Strategies
91+
92+
Consider these cleanup strategies for different scenarios:
93+
94+
### Development Machine
95+
96+
For your primary development machine:
97+
98+
```ts
99+
startProxy({
100+
from: 'localhost:3000',
101+
to: 'myapp.test',
102+
cleanup: {
103+
hosts: true, // Clean up hosts entries to avoid conflicts
104+
certs: false // Keep certificates for faster startup next time
105+
}
106+
})
107+
```
108+
109+
### CI/CD Environment
110+
111+
For continuous integration or deployment environments:
112+
113+
```ts
114+
startProxy({
115+
from: 'localhost:3000',
116+
to: 'myapp.test',
117+
cleanup: {
118+
hosts: true, // Clean up hosts entries
119+
certs: true // Clean up certificates to avoid accumulation
120+
}
121+
})
122+
```
123+
124+
### Shared Development Environments
125+
126+
For environments shared by multiple developers:
127+
128+
```ts
129+
startProxy({
130+
from: 'localhost:3000',
131+
to: 'myapp.test',
132+
cleanup: {
133+
hosts: true, // Clean up hosts entries to avoid conflicts
134+
certs: true // Clean up certificates to avoid conflicts
135+
}
136+
})
137+
```
138+
139+
## Orphaned Resources
140+
141+
If rpx exits unexpectedly (e.g., process killed), it might leave orphaned resources. You can clean these up:
142+
143+
### Hosts File
144+
145+
Entries in your hosts file will look like this:
146+
147+
```
148+
# Added by rpx
149+
127.0.0.1 myapp.test
150+
::1 myapp.test
151+
```
152+
153+
You can manually remove these or run:
154+
155+
```bash
156+
# Clean up specific domains
157+
rpx cleanup --domains myapp.test,api.myapp.test --hosts
158+
159+
# Clean up all domains added by rpx (future version)
160+
rpx cleanup --all --hosts
161+
```
162+
163+
### Certificates
164+
165+
Certificates are stored in specific locations:
166+
167+
- Default: `~/.stacks/ssl/`
168+
- Custom: Locations specified in your configuration
169+
170+
You can manually delete these or run:
171+
172+
```bash
173+
# Clean up certificates for specific domains
174+
rpx cleanup --domains myapp.test,api.myapp.test --certs
175+
176+
# Clean up all certificates (future version)
177+
rpx cleanup --all --certs
178+
```
179+
180+
## Best Practices
181+
182+
1. **Enable hosts cleanup** for most scenarios to avoid hosts file pollution
183+
2. **Keep certificates** for domains you use regularly (faster startup)
184+
3. **Clean up certificates** for temporary or rarely used domains
185+
4. **Use descriptive domain names** to make it clear which certificates and hosts entries belong to which projects
186+
5. **Consider domain namespacing** (e.g., `project1.test`, `project2.test`) to organize your development environment

‎docs/advanced/custom-certificates.md‎

Lines changed: 164 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,164 @@
1+
# Custom Certificates
2+
3+
While rpx can automatically generate SSL certificates, you may want to use your own custom certificates in certain scenarios. This guide shows you how to use custom certificates with rpx.
4+
5+
## When to Use Custom Certificates
6+
7+
Custom certificates are useful when:
8+
9+
- You already have certificates from another system
10+
- You need to share certificates across multiple tools or systems
11+
- You have specific certificate requirements not covered by the automatic generation
12+
- You're working in a corporate environment with specific certificate policies
13+
14+
## Using Existing Certificates
15+
16+
To use existing certificates with rpx, specify the paths in your configuration:
17+
18+
```ts
19+
import { startProxy } from '@stacksjs/rpx'
20+
21+
startProxy({
22+
from: 'localhost:3000',
23+
to: 'myapp.test',
24+
https: {
25+
certPath: '/path/to/your/certificate.crt',
26+
keyPath: '/path/to/your/private.key',
27+
// Optional CA certificate if you have one
28+
caCertPath: '/path/to/your/ca.crt'
29+
}
30+
})
31+
```
32+
33+
With the CLI:
34+
35+
```bash
36+
rpx --from localhost:3000 --to myapp.test --certPath /path/to/your/certificate.crt --keyPath /path/to/your/private.key
37+
```
38+
39+
## Certificate Requirements
40+
41+
Your custom certificates should meet these requirements:
42+
43+
1. The certificate must be valid for the domain you're using
44+
2. The private key should be unencrypted (no passphrase)
45+
3. The certificate should be in PEM format
46+
4. If using a CA certificate, it should also be in PEM format
47+
48+
## Creating Custom Certificates
49+
50+
If you want to create your own certificates instead of using rpx's automatic generation, you can use tools like OpenSSL:
51+
52+
### Create a CA Certificate
53+
54+
```bash
55+
# Generate a private key for the CA
56+
openssl genrsa -out ca.key 2048
57+
58+
# Create a CA certificate
59+
openssl req -x509 -new -nodes -key ca.key -sha256 -days 365 -out ca.crt -subj "/C=US/ST=State/L=City/O=Organization/CN=My Custom CA"
60+
```
61+
62+
### Create a Server Certificate
63+
64+
```bash
65+
# Generate a private key for the server
66+
openssl genrsa -out server.key 2048
67+
68+
# Create a certificate signing request (CSR)
69+
openssl req -new -key server.key -out server.csr -subj "/C=US/ST=State/L=City/O=Organization/CN=myapp.test"
70+
71+
# Create a config file for subject alternative names
72+
cat > san.cnf <<EOF
73+
[req]
74+
distinguished_name = req_distinguished_name
75+
req_extensions = v3_req
76+
prompt = no
77+
78+
[req_distinguished_name]
79+
CN = myapp.test
80+
81+
[v3_req]
82+
subjectAltName = @alt_names
83+
84+
[alt_names]
85+
DNS.1 = myapp.test
86+
DNS.2 = *.myapp.test
87+
DNS.3 = localhost
88+
IP.1 = 127.0.0.1
89+
EOF
90+
91+
# Sign the CSR with your CA
92+
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 365 -sha256 -extfile san.cnf -extensions v3_req
93+
```
94+
95+
## Using mkcert
96+
97+
[mkcert](https://github.com/FiloSottile/mkcert) is a great tool for creating locally-trusted development certificates. You can use certificates generated by mkcert with rpx:
98+
99+
```bash
100+
# Install mkcert
101+
brew install mkcert # macOS
102+
# or your system's package manager
103+
104+
# Install the local CA in the system trust store
105+
mkcert -install
106+
107+
# Generate certificates for your domains
108+
mkcert myapp.test "*.myapp.test" localhost 127.0.0.1 ::1
109+
110+
# This creates:
111+
# - myapp.test+4.pem (the certificate)
112+
# - myapp.test+4-key.pem (the private key)
113+
```
114+
115+
Then use these with rpx:
116+
117+
```ts
118+
startProxy({
119+
from: 'localhost:3000',
120+
to: 'myapp.test',
121+
https: {
122+
certPath: './myapp.test+4.pem',
123+
keyPath: './myapp.test+4-key.pem',
124+
}
125+
})
126+
```
127+
128+
## Certificate Locations
129+
130+
When using custom certificates, you should:
131+
132+
1. Store them in a secure location
133+
2. Ensure the user running rpx has read access to them
134+
3. Consider excluding them from version control (add to `.gitignore`)
135+
4. Back them up if they're important
136+
137+
For development, a common pattern is to store certificates in a `certs/` folder in your project:
138+
139+
```
140+
myproject/
141+
├── certs/
142+
│ ├── ca.crt
143+
│ ├── server.crt
144+
│ └── server.key
145+
├── src/
146+
├── rpx.config.ts
147+
└── ...
148+
```
149+
150+
Then reference them in your configuration:
151+
152+
```ts
153+
import path from 'node:path'
154+
155+
export default {
156+
from: 'localhost:3000',
157+
to: 'myapp.test',
158+
https: {
159+
certPath: path.join(__dirname, 'certs', 'server.crt'),
160+
keyPath: path.join(__dirname, 'certs', 'server.key'),
161+
caCertPath: path.join(__dirname, 'certs', 'ca.crt'),
162+
}
163+
}
164+
```

0 commit comments

Comments
 (0)