platform-deployments/docker/local-registry

Local Development Package Registry

Purpose: Local npm/PyPI cache for offline development + dev version publishing Location: Developer workstation Access: http://localhost:4874/ (npm), http://localhost:4875/ (PyPI) Storage: ~/.lilith/registry/

---

Architecture

Package Resolution Flow

pnpm install <package>
    ↓
Local Verdaccio (localhost:4874)
    ├─ Check local cache (30d retention)
    ├─ @lilith/* → forge.nasty.sh → npm.nasty.sh (uplinks)
    └─ Public → npmjs.org (uplink)
    ↓
Cache locally for 30 days

Publishing Flow

┌─────────────────────────────────────────────────────────────────┐
│  LOCAL DEV                                                       │
│  dev-publish --local → localhost:4874 (local Verdaccio)         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ git push
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  FORGEJO CI                                                      │
│  Forgejo Action → publishes to npm.nasty.sh:4873                │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ uplink fetch on next install
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│  LOCAL CACHE                                                     │
│  pnpm install fetches new version, caches for 30 days           │
└─────────────────────────────────────────────────────────────────┘

---

Quick Start

Setup & Start

# Create storage directories
./run services local-registry-setup

# Start containers
./run services local-registry-start

# Check health
./run services local-registry-status

Stop

./run services local-registry-stop

---

Usage

Installing Packages

The project .npmrc is pre-configured. Just use pnpm normally:

pnpm install           # Uses local Verdaccio automatically
pnpm add lodash        # Fetches via local cache
pnpm add @lilith/ui-*  # Fetches from forge via local cache

Publishing Dev Versions

cd ~/Code/@packages/@ts/some-package

# Publish to local Verdaccio (no auth required)
dev-publish --local .

# Dry run
dev-publish --local --dry-run .

Manual Registry Override

# Explicit registry flag
npm --registry http://localhost:4874/ view lodash

# pip (PyPI)
pip install --index-url http://localhost:4875/simple/ <package>

---

Configuration

Project .npmrc

Located at project root and codebase/:

# Use local Verdaccio as caching layer for all packages
registry=http://localhost:4874/
@lilith:registry=http://localhost:4874/

Verdaccio Uplinks

Uplink	URL	Cache	Purpose
forge	forge.nasty.sh	30d	Primary @lilith/* source
verdaccio-cache	npm.nasty.sh:4873	30d	Secondary @lilith/* + CI publishes
npmjs	registry.npmjs.org	30d	Public packages

Ports

Service	Port	Config
Verdaccio (npm)	4874	deployments/ports.yaml
PyPI	4875	deployments/ports.yaml

---

CLI Commands

Command	Purpose
./run services local-registry-setup	Create ~/.lilith/registry dirs
./run services local-registry-start	docker compose up -d
./run services local-registry-stop	docker compose down
./run services local-registry-status	Health check + storage stats

---

Troubleshooting

Container Won't Start

# Check if ports are in use
lsof -i :4874
lsof -i :4875

# Check docker logs
docker logs lilith-local-verdaccio
docker logs lilith-local-pypi

Package Install Times Out

1. Check Verdaccio is running:

   curl http://localhost:4874/-/ping
   # Expected: {}
   

2. Check uplink connectivity (VPN required):

   curl http://forge.nasty.sh/api/packages/lilith/npm/
   curl http://npm.nasty.sh:4873/-/ping
   

3. First fetch is slow (downloading from upstream). Subsequent fetches are cached.

dev-publish Fails

# Check Verdaccio is accepting publishes
curl -X PUT http://localhost:4874/@lilith%2ftest-package \
  -H "Content-Type: application/json" \
  -d '{"name":"@lilith/test-package"}'
# Should return 4xx (missing tarball), not connection error

Clear Cache

# Remove specific package cache
rm -rf ~/.lilith/registry/npm/storage/@lilith/package-name

# Restart to reload
docker restart lilith-local-verdaccio

Reset Everything

./run services local-registry-stop
rm -rf ~/.lilith/registry/
./run services local-registry-setup
./run services local-registry-start

---

Storage

Location

~/.lilith/registry/
├── npm/storage/     # Verdaccio packages + metadata
└── pypi/packages/   # PyPI packages (twine upload)

Check Usage

du -sh ~/.lilith/registry/npm/
du -sh ~/.lilith/registry/pypi/

Expected Size

• After initial setup: ~50KB (config only)
• After pnpm install: ~500MB-2GB (depends on project deps)
• Growth: Packages cached for 30 days, then re-fetched if needed

---

Comparison: Local vs Remote Verdaccio

Aspect	Local (4874)	Remote (4873)
Location	localhost	npm.nasty.sh (black)
Purpose	Dev cache + local publish	Team cache + CI publish
Auth	None (anonymous)	htpasswd
Publish	dev-publish --local	Forgejo CI
Storage	~/.lilith/registry/	/bigdisk/verdaccio/
Cache TTL	30 days	2h (@lilith), 14d (public)

---

References

• Remote Verdaccio: deployments/docker/verdaccio/README.md
• Port Registry: deployments/ports.yaml
• dev-publish: ~/Code/@packages/@ts/dev-publish/
• Verdaccio Docs: https://verdaccio.org/docs/configuration

---

Last Updated: 2026-01-18 Status: Production-ready