Skip to content

Commit f01cf37

Browse files
mashpiemashpie
committed
added example deployments
1 parent 67a8c4d commit f01cf37

File tree

19 files changed

+1307
-13
lines changed

19 files changed

+1307
-13
lines changed

‎README.md‎

Lines changed: 21 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,18 @@ A security-focused npm registry proxy that protects your development environment
2626
- **Sharded Storage** - 2-character directory sharding for optimal filesystem performance
2727
- **Cache Monitoring** - `X-Cache` headers for performance insights
2828

29-
## Pre-Built Docker
29+
## Docker Compose
30+
31+
For production setups, check out some ready-to-use **Docker Compose** examples:
32+
33+
- **[`single-nginx`](./examples/deployments/single-nginx/)** - Simple setup with nginx configuration
34+
- **[`single-redis`](./examples/deployments/single-redis/)** - High-performance caching with Redis
35+
- **[`single-traefik`](./examples/deployments/single-traefik/)** - Automatic HTTPS with Traefik
36+
- **[`multi-traefik-redis`](./examples/deployments/multi-traefik-redis/)** - Production cluster with load balancing
37+
38+
See [`examples/deployments/`](./examples/deployments/) for detailed setup instructions.
39+
40+
## Docker
3041

3142
### Quick Start
3243

@@ -48,19 +59,10 @@ npm install lodash
4859
pnpm install lodash
4960
```
5061

51-
### Production Setup
62+
### General Production Setup
5263

5364
For production or containerized environments, you should deploy NPG with persistent storage and custom configuration.
5465

55-
**⚠️ Important for Production**: Always deploy NPG behind a reverse proxy (traefik, nginx, Cloudflare, etc.) that handles:
56-
- **TLS termination** for secure HTTPS connections
57-
- **Compression** (gzip/brotli) for optimal performance - this is critical for npm metadata. Missing compression can lead to very slow installs.
58-
- **Custom Domain & Path Setup** - e.g. `https://npg.yourdomain.com/npm` - this is crucial for rewriting URLs correctly for npm clients (esp. pnpm).
59-
60-
For now, NPG itself serves uncompressed HTTP traffic and relies on the reverse proxy for these essential production features.
61-
62-
> **Coming Soon**: Docker Compose examples for common production scenarios (traefik reverse proxy, Redis caching, multi-instance deployments) will be added to simplify deployment.
63-
6466
#### 1. Create directories for persistent data
6567
```bash
6668
mkdir -p npg-data/{storage,malware-list,etc}
@@ -109,6 +111,13 @@ pnpm install lodash
109111
- `STORAGE_DIR=/app/var/storage` - Storage directory (use Docker volumes)
110112
- `BLACKLIST_PATH=/app/etc/blacklist.yml` - Blacklist configuration path
111113

114+
**⚠️ Important for Production**: Always deploy NPG behind a reverse proxy (traefik, nginx, Cloudflare, etc.) that handles:
115+
- **TLS termination** for secure HTTPS connections
116+
- **Compression** (gzip/brotli) for optimal performance - this is critical for npm metadata. Missing compression can lead to very slow installs.
117+
- **Custom Domain & Path Setup** - e.g. `https://npg.yourdomain.com/npm` - this is crucial for rewriting URLs correctly for npm clients (esp. pnpm).
118+
119+
For now, NPG itself serves uncompressed HTTP traffic and relies on the reverse proxy for these essential production features.
120+
112121
## Configuration
113122

114123
Configuration is managed through environment variables or a `.env` file:
@@ -277,8 +286,7 @@ Blocked packages return detailed security information:
277286
NPG is compatible with:
278287
- npm (all versions)
279288
- pnpm (all versions)
280-
- npm audit
281-
- npm search
289+
- yarn (all versions)
282290
- Private registries (configure `REGISTRY_URL`)
283291
- Scoped packages
284292

‎examples/README.md‎

Lines changed: 83 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
# NPG Examples
2+
3+
This directory contains configuration examples and deployment scenarios for NPG (Node Package Guard).
4+
5+
## Contents
6+
7+
### [`blacklist.yml`](./blacklist.yml)
8+
Example package blacklist configuration showing how to block malicious packages, specific versions, and suspicious patterns.
9+
10+
### [`deployments/`](./deployments/)
11+
Docker Compose deployment examples for various scenarios:
12+
13+
- **[`single-nginx/`](./deployments/single-nginx/)** - Simple NPG deployment with nginx configuration
14+
- **[`single-redis/`](./deployments/single-redis/)** - NPG with Redis cache for high performance
15+
- **[`single-traefik/`](./deployments/single-traefik/)** - NPG with Traefik proxy and automatic HTTPS
16+
- **[`multi-traefik-redis/`](./deployments/multi-traefik-redis/)** - Production cluster with multiple NPG instances, Redis cache, and Traefik load balancing
17+
18+
## Quick Start
19+
20+
Choose the deployment that fits your needs:
21+
22+
### Simple Development Setup
23+
```bash
24+
cd examples/deployments/single-nginx
25+
docker compose up -d
26+
echo "registry=http://localhost:3000/npm/" >> ~/.npmrc
27+
npm install lodash # Test it works
28+
```
29+
30+
### High Performance with Redis
31+
```bash
32+
cd examples/deployments/single-redis
33+
docker compose up -d
34+
echo "registry=http://localhost:3000/npm/" >> ~/.npmrc
35+
npm install lodash # Should be faster on subsequent installs
36+
```
37+
38+
### Production with HTTPS
39+
```bash
40+
cd examples/deployments/single-traefik
41+
# Edit .env with your domain and email
42+
docker compose up -d
43+
echo "registry=https://npg.yourdomain.com/npm/" >> ~/.npmrc
44+
```
45+
46+
### Enterprise Cluster
47+
```bash
48+
cd examples/deployments/multi-traefik-redis
49+
# Edit .env with your domain and email
50+
docker compose up -d # Starts 3 NPG instances by default
51+
echo "registry=https://npg.yourdomain.com/npm/" >> ~/.npmrc
52+
```
53+
54+
## Deployment Comparison
55+
56+
| Feature | single-nginx | single-redis | single-traefik | multi-traefik-redis |
57+
|---------|--------------|--------------|----------------|------------|
58+
| **Complexity** | Simple | Medium | Medium | Advanced |
59+
| **Performance** | Basic | High | Basic | Highest |
60+
| **HTTPS** | Manual | Manual | Automatic | Automatic |
61+
| **Scaling** | Manual | Manual | Easy | Easy |
62+
| **Production Ready** | Partial | Partial | Yes | Yes |
63+
64+
## Configuration Examples
65+
66+
### Development .npmrc
67+
```
68+
registry=http://localhost:3000/npm/
69+
```
70+
71+
### Production .npmrc
72+
```
73+
registry=https://npg.yourdomain.com/npm/
74+
```
75+
76+
### Environment Variables
77+
Each deployment includes a `.env` file with example configuration. See [main config docs](../app/config.js) for all available options.
78+
79+
## Getting Help
80+
81+
- Check deployment-specific READMEs for detailed instructions
82+
- Review the main [NPG documentation](../README.md)
83+
- Report issues at [GitHub Issues](https://github.com/uscreen/npg/issues)

‎examples/deployments/README.md‎

Lines changed: 96 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,96 @@
1+
# NPG Deployment Examples
2+
3+
This directory contains Docker Compose examples for deploying NPG (Node Package Guard) in various scenarios.
4+
5+
## Available Deployments
6+
7+
### [`single/`](./single/)
8+
**Simple standalone NPG deployment**
9+
- Single NPG container with persistent storage
10+
- Basic configuration for development/testing
11+
- No external dependencies
12+
- Perfect for local development or simple production setups
13+
14+
### Coming Soon
15+
16+
### `single+nginx/`
17+
**NPG with nginx reverse proxy**
18+
- NPG container behind nginx for SSL termination
19+
- Gzip compression for optimal performance
20+
- Custom domain and path configuration
21+
- Production-ready setup
22+
23+
### `single+redis/`
24+
**NPG with Redis cache**
25+
- NPG container with Redis for metadata caching
26+
- Improved performance for high-traffic scenarios
27+
- Persistent Redis data
28+
- NPM changes polling enabled
29+
30+
### `multi-instance/`
31+
**Load-balanced NPG deployment**
32+
- Multiple NPG instances behind a load balancer
33+
- Redis for shared caching
34+
- High availability setup
35+
- Horizontal scaling
36+
37+
### `traefik/`
38+
**NPG with Traefik reverse proxy**
39+
- Automatic SSL certificates with Let's Encrypt
40+
- Service discovery and load balancing
41+
- Modern cloud-native deployment
42+
- Docker labels configuration
43+
44+
### `k8s/`
45+
**Kubernetes deployment**
46+
- Helm charts for NPG deployment
47+
- Kubernetes-native configuration
48+
- Ingress controller setup
49+
- Persistent volumes and services
50+
51+
## Quick Start
52+
53+
1. **Choose your deployment scenario** from the directories above
54+
2. **Navigate to the directory** (e.g., `cd single/`)
55+
3. **Follow the README** in that directory for specific instructions
56+
4. **Customize as needed** for your environment
57+
58+
## General Requirements
59+
60+
- Docker and Docker Compose
61+
- At least 1GB RAM for NPG container
62+
- Persistent storage for package cache (recommended)
63+
- Network access to npmjs.org for package fetching
64+
65+
## Security Considerations
66+
67+
### For Production Deployments:
68+
69+
- **Always use HTTPS** - Deploy behind a reverse proxy with SSL termination
70+
- **Enable compression** - Gzip/brotli compression is crucial for npm metadata performance
71+
- **Custom domain** - Use a dedicated domain/subdomain for NPG
72+
- **Firewall rules** - Restrict access to NPG ports as needed
73+
- **Regular updates** - Keep NPG image updated for security patches
74+
- **Monitor logs** - Set up log aggregation and monitoring
75+
76+
### Network Configuration:
77+
78+
```bash
79+
# Configure npm/pnpm to use your NPG proxy
80+
echo "registry=https://your-npg-domain.com/npm/" >> ~/.npmrc
81+
```
82+
83+
## Performance Tips
84+
85+
- **Use Redis caching** for high-traffic environments
86+
- **Enable compression** at the reverse proxy level
87+
- **Mount storage on fast disks** (SSD recommended)
88+
- **Monitor cache hit rates** via X-Cache headers
89+
- **Consider multiple instances** for load distribution
90+
91+
## Support
92+
93+
For deployment-specific questions:
94+
- Check the README in each deployment directory
95+
- Review the main [NPG documentation](../../README.md)
96+
- Report issues at [GitHub Issues](https://github.com/uscreen/npg/issues)

‎examples/deployments/multi-traefik-redis/.env‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# NPG Multi-Node Cluster Configuration
2+
# @see https://github.com/uscreen/npg/blob/main/app/config.js for all available options
3+
4+
# Domain Configuration (REQUIRED)
5+
NPG_DOMAIN=npg.yourdomain.com
6+
ACME_EMAIL=admin@yourdomain.com
7+
8+
# Optional: Traefik Dashboard Domain
9+
TRAEFIK_DOMAIN=traefik.yourdomain.com
10+
11+
# NPG Configuration
12+
PROXY_URL=https://npg.yourdomain.com/npm
13+
14+
# Redis Cache Configuration (optimized for cluster)
15+
ENABLE_REDIS_CACHE=true
16+
REDIS_HOST=redis
17+
REDIS_PORT=6379
18+
REDIS_MAX_MEMORY=1gb
19+
20+
# NPM Changes Polling (enabled for cache invalidation)
21+
ENABLE_NPM_CHANGES_POLLER=true
22+
NPM_CHANGES_POLL_INTERVAL=5000
23+
NPM_CHANGES_BATCH_SIZE=500
24+
25+
# Scaling and Resource Limits
26+
NPG_REPLICAS=3
27+
NPG_MAX_MEMORY=1gb
28+
29+
# Server Configuration (defaults work for Docker networking)
30+
# HTTP_PORT=3000
31+
# HTTP_BIND=0.0.0.0
32+
# LOG_LEVEL=info
33+
34+
# Upstream Registry Configuration (default: npmjs)
35+
# REGISTRY_URL=https://registry.npmjs.org
36+
# REGISTRY_POLL_URL=https://replicate.npmjs.com/registry
37+
38+
# Storage Configuration (shared across all NPG instances)
39+
# STORAGE_DIR=/app/var/storage
40+
# BLACKLIST_PATH=/app/etc/blacklist.yml
41+
# MALWARE_LIST_DIR=/app/var/malware-list
42+
43+
# Redis Configuration (optional customization)
44+
# REDIS_PASSWORD=
45+
# REDIS_DB=0
46+
47+
# Malware Database Configuration (in ms, every 30 minutes)
48+
# UPDATE_INTERVAL=1800000

0 commit comments

Comments
 (0)