stack.gallery/registry
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add initial README with project overview, features, and setup instructions

Browse Source
This commit is contained in:
Jürgen Kunz
2025-11-27 23:53:05 +00:00
parent 9f5e7e2558
commit 3dfc882f85
1 changed files with 232 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

232
readme.md Normal file
View File

@@ -0,0 +1,232 @@
# @stack.gallery/registry 📦
**Enterprise-grade multi-protocol package registry** built with Deno and TypeScript. Host your own private NPM, Docker/OCI, Maven, Cargo, PyPI, Composer, and RubyGems registry with a unified, beautiful web interface.
## Issue Reporting and Security
For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
## ✨ Features
- 🔐 **Multi-Protocol Support** - NPM, OCI/Docker, Maven, Cargo, PyPI, Composer, RubyGems
- 🏢 **Organizations & Teams** - Fine-grained access control with role-based permissions
- 🎫 **API Tokens** - Scoped tokens for CI/CD and programmatic access
- 🔍 **Upstream Caching** - Proxy and cache packages from public registries
- 📊 **Audit Logging** - Complete audit trail for compliance and security
- 🎨 **Modern Web UI** - Angular 19 dashboard for package management
- ⚡ **Deno Runtime** - Fast, secure, TypeScript-first backend
- 🗄️ **MongoDB + S3** - Scalable storage with smartdata ORM
## 🚀 Quick Start
### Prerequisites
- **Deno** >= 1.40
- **MongoDB** >= 4.4
- **S3-compatible storage** (MinIO, AWS S3, etc.)
- **Node.js** >= 18 (for UI development)
### Installation
```bash
# Clone the repository
git clone https://code.foss.global/stack.gallery/registry.git
cd registry
# Install UI dependencies
cd ui && pnpm install && cd ..
# Build the UI
pnpm run build
```
### Configuration
Create a `.nogit/env.json` file for local development:
```json
{
"MONGODB_URL": "mongodb://localhost:27017",
"MONGODB_NAME": "stackregistry",
"S3_HOST": "localhost",
"S3_PORT": "9000",
"S3_ACCESSKEY": "minioadmin",
"S3_SECRETKEY": "minioadmin",
"S3_BUCKET": "registry",
"S3_USESSL": false,
"JWT_SECRET": "your-secure-secret-key",
"ADMIN_EMAIL": "admin@example.com",
"ADMIN_PASSWORD": "your-admin-password"
}
```
Or use environment variables:
| Variable | Description | Default |
|----------|-------------|---------|
| `MONGODB_URL` | MongoDB connection string | `mongodb://localhost:27017` |
| `MONGODB_DB` | Database name | `stackgallery` |
| `S3_ENDPOINT` | S3 endpoint URL | `http://localhost:9000` |
| `S3_ACCESS_KEY` | S3 access key | `minioadmin` |
| `S3_SECRET_KEY` | S3 secret key | `minioadmin` |
| `S3_BUCKET` | S3 bucket name | `registry` |
| `JWT_SECRET` | JWT signing secret | `change-me-in-production` |
| `ADMIN_EMAIL` | Default admin email | `admin@stack.gallery` |
| `ADMIN_PASSWORD` | Default admin password | `admin` |
| `PORT` | HTTP server port | `3000` |
### Running
```bash
# Development mode (with hot reload)
pnpm run watch
# Production mode
deno run --allow-all mod.ts server
# Or with Deno tasks
deno task start
```
The registry will be available at `http://localhost:3000`
## 🏗️ Architecture
```
registry/
├── mod.ts # Entry point
├── ts/
│ ├── registry.ts # Main StackGalleryRegistry class
│ ├── cli.ts # CLI command handler
│ ├── plugins.ts # Centralized dependencies
│ ├── api/
│ │ ├── router.ts # REST API router with JWT auth
│ │ └── handlers/ # API endpoint handlers
│ ├── models/ # MongoDB models (smartdata)
│ │ ├── user.ts
│ │ ├── organization.ts
│ │ ├── repository.ts
│ │ ├── package.ts
│ │ ├── session.ts
│ │ └── ...
│ ├── services/ # Business logic
│ │ ├── auth.service.ts
│ │ ├── permission.service.ts
│ │ ├── token.service.ts
│ │ └── audit.service.ts
│ ├── providers/ # Registry protocol integrations
│ │ ├── auth.provider.ts
│ │ └── storage.provider.ts
│ └── interfaces/ # TypeScript types
└── ui/ # Angular 19 web interface
```
## 📡 API Endpoints
### Authentication
| Method | Endpoint | Description |
|--------|----------|-------------|
| `POST` | `/api/v1/auth/login` | Login with email/password |
| `POST` | `/api/v1/auth/refresh` | Refresh access token |
| `POST` | `/api/v1/auth/logout` | Logout (invalidate session) |
| `GET` | `/api/v1/auth/me` | Get current user |
### Organizations
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/v1/organizations` | List organizations |
| `POST` | `/api/v1/organizations` | Create organization |
| `GET` | `/api/v1/organizations/:id` | Get organization details |
| `PUT` | `/api/v1/organizations/:id` | Update organization |
| `DELETE` | `/api/v1/organizations/:id` | Delete organization |
### Repositories
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/v1/organizations/:orgId/repositories` | List repositories |
| `POST` | `/api/v1/organizations/:orgId/repositories` | Create repository |
| `GET` | `/api/v1/repositories/:id` | Get repository details |
### Packages
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/v1/packages` | List packages |
| `GET` | `/api/v1/packages/:id` | Get package details |
| `GET` | `/api/v1/packages/:id/versions` | List package versions |
### API Tokens
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/v1/tokens` | List user's tokens |
| `POST` | `/api/v1/tokens` | Create new token |
| `DELETE` | `/api/v1/tokens/:id` | Revoke token |
## 🔌 Protocol Endpoints
The registry handles protocol-specific endpoints automatically via `@push.rocks/smartregistry`:
- **NPM**: `/-/*`, `/@scope/*`
- **OCI/Docker**: `/v2/*`
- **Maven**: `/maven2/*`
- **PyPI**: `/simple/*`, `/pypi/*`
- **Cargo**: `/api/v1/crates/*`
- **Composer**: `/packages.json`, `/p/*`
- **RubyGems**: `/api/v1/gems/*`, `/gems/*`
## 🔧 Technology Stack
| Component | Technology |
|-----------|------------|
| Runtime | Deno |
| Language | TypeScript |
| Database | MongoDB via `@push.rocks/smartdata` |
| Storage | S3 via `@push.rocks/smartbucket` |
| Registry | `@push.rocks/smartregistry` |
| Frontend | Angular 19 |
| Auth | JWT with session management |
## 🛡️ Security Features
- **JWT Authentication** - Short-lived access tokens with refresh flow
- **Session Management** - Track and invalidate active sessions
- **Scoped API Tokens** - Fine-grained permissions per token
- **RBAC** - Organization-level role-based access control
- **Audit Logging** - Comprehensive action logging
- **Password Hashing** - PBKDF2-style hashing with salts
## 📜 CLI Commands
```bash
# Start the server
deno run --allow-all mod.ts server [--ephemeral]
# Show help
deno run --allow-all mod.ts help
```
Options:
- `--ephemeral` / `-e` - Load config from `.nogit/env.json` instead of environment variables
## License and Legal Information
This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository.
**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
### Trademarks
This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.
### Company Information
Task Venture Capital GmbH
Registered at District court Bremen HRB 35230 HB, Germany
For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.
By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.