Crude Registry

A simple npm-compatible package registry built with Astro, Effect-TS, Drizzle ORM and AWS S3 for storage. Built to support private package management and distribution.

Note

Crude Registry is designed for managing and published scoped packages only!

Important

Crude Registry is still in early development and should not be used in production yet. Use at your own risk.

Features

• Token-based authentication for uploads and downloads
• S3 storage for package tarballs
• SQLite/libsql database for metadata
• Built with Astro and Effect
• Full web-ui for users and admins
• npm CLI compatible
• Remote connection to external auth server for per-package/group licensing
• Dockerfile for quick production setup

Supported NPM Commands

• publish
• unpublish
• info
• audit
• install
• deprecate
• ping
• dist-tag
• login
• logout
• whoami

Setup

1. Install dependencies:

pnpm install

2. Copy .env.demo to .env and configure:

cp ./package/.env.demo ./package/.env

3. Generate and run database migrations:

pnpm run generate
pnpm run migrate

Save the token output - you'll need it to publish and download packages.

4. Start the server:

pnpm run dev

5. Create the initial Super Admin

Open the web-ui at http://localhost:4321 and signup to create the initial Super Admin user.

API Endpoints

Docs

• GET /api/docs - Scalar API docs

Health Check

• GET /api/health - Health Check status endpoint

Download statistics

• GET /api/stats/downloads - Lookup download stats (optionally by package and/or token query param) (requires auth)

Package Management

• PUT /:package - Publish a package (requires auth)
• GET /:package - Get package metadata (requires auth)
• GET /:package/-/:filename - Download package tarball (requires auth)

Get Package Metadata

curl http://localhost:4321/@your-org/your-package

Download Package

curl http://localhost:4321/@your-org/your-package/-/your-package-1.0.0.tgz \
  -H "Authorization: Bearer YOUR_TOKEN"

Usage

Configure npm to use the registry

Configure registry for your scope:

# Private registry for your packages
npm config set @your-org:registry http://localhost:4321
npm config set //localhost:4321/:_authToken YOUR_TOKEN

Publishing a package

npm publish

Installing a package

npm install @your-org/your-package

Configuration

See .env.example for all available configuration options.

Security Considerations

1. Always use HTTPS in production - Set up a reverse proxy (nginx, Caddy) with SSL
2. Rotate tokens regularly - Create new tokens and revoke old ones
3. Limit S3 bucket access - Use IAM policies to restrict access
4. Monitor downloads - Check the downloads table for unusual activity
5. Backup your database - Regular backups of the SQLite database
6. Use strong tokens - The generated tokens are cryptographically secure

Troubleshooting

Cannot publish packages

• Crude Registry can only handle Scoped packages
• Ensure your auth token is correctly configured
• Check that the token hasn't been revoked
• Verify S3 credentials are correct

Cannot download packages

• Downloads require authentication
• Ensure Authorization header is present
• Check that the package version exists

Database errors

• Run migrations: npm run db:migrate
• Check DATABASE_URL is correct
• Ensure write permissions for SQLite file

S3 errors

• Verify AWS credentials
• Check bucket exists and has correct permissions
• For MinIO/S3-compatible: set S3_ENDPOINT