Repsy: The Open Source Universal Package Repository

Repsy is an open-source, universal package repository that makes it easy to host, manage, and distribute your packages across multiple ecosystems — all in one place. With support for popular formats including Golang, Cargo (Rust), Docker, Maven, NPM, PyPI, and more, Repsy helps streamline your development workflows and supports teams of any size.

Table of Contents

• Features
• Quick Start
• HTTPS / SSL
• Installation

- Using Docker (H2 - Embedded) - Using Docker (PostgreSQL) - Using Docker Compose (PostgreSQL) - Manual Installation

• Configuration
• Usage
• Troubleshooting
• Development
• License

Features

• Repository Management: Create, manage, and organize repositories
• Multi-Protocol Support: Golang, Cargo (Rust), Maven, npm, PyPI, Docker registries
• User Authentication: Secure JWT-based authentication
• Deploy Tokens: Secure token-based deployment mechanism
• Real-time Dashboard: Monitor repository activity
• RESTful API: Comprehensive REST API
• Database Support: H2 (embedded) and PostgreSQL
• Docker Ready: Complete containerization support

Quick Start

The fastest way to get Repsy up and running (uses embedded H2 database — no external dependencies):

docker run -d \
  --name repsy \
  -p 8080:8080 \
  -p 9090:9090 \
  repo.repsy.io/repsy/os/repsy:latest

Access the application:

• Backend API & Frontend (Web UI): http://localhost:8080
• Repository Operations: http://localhost:9090

Default Admin Credentials:

• Username: admin
• Password: since ADMININITIALPASSWORD is not set, a random password is generated on first startup. Retrieve it from the logs:

docker logs repsy | grep "password"

Note: The H2 database is stored at /app/data inside the container. File storage defaults to ~/.repsy on the host and is not covered by the volume mount. Set STORAGEBASEPATH to persist artifacts inside the same volume (see Option 1).

HTTPS / SSL

Repsy OS supports optional, per-port HTTPS. HTTP ports (8080, 9090) remain open at all times — SSL adds new ports alongside them and does not replace them.

Generating a self-signed certificate

keytool -genkeypair \
  -alias repsy \
  -keyalg RSA \
  -keysize 2048 \
  -storetype PKCS12 \
  -keystore keystore.p12 \
  -validity 365 \
  -storepass changeit \
  -keypass changeit \
  -dname "CN=localhost, O=Repsy" \
  -ext "SAN=DNS:localhost,IP:127.0.0.1"

Environment variables

| Variable | Description | Default | |---|---|---| | APISSLENABLED | Enable HTTPS for the API port | false | | APISSLPORT | HTTPS port for the API | 8443 | | APISSLKEYSTOREPATH | Path to keystore file (e.g. file:/app/certs/api.p12) | — | | APISSLKEYSTOREPASSWORD | Keystore password | — | | APISSLKEYSTORETYPE | Keystore type | PKCS12 | | APISSLKEY_ALIAS | Key alias inside the keystore | repsy | | REPOSSLENABLED | Enable HTTPS for the repo port | false | | REPOSSLPORT | HTTPS port for the repo | 9443 | | REPOSSLKEYSTOREPATH | Path to keystore file (e.g. file:/app/certs/repo.p12) | — | | REPOSSLKEYSTOREPASSWORD | Keystore password | — | | REPOSSLKEYSTORETYPE | Keystore type | PKCS12 | | REPOSSLKEY_ALIAS | Key alias inside the keystore | repsy |

Docker run example

docker run \
  -v /host/certs/keystore.p12:/app/certs/keystore.p12 \
  -e APISSLENABLED=true \
  -e APISSLKEYSTOREPATH=file:/app/certs/keystore.p12 \
  -e APISSLKEYSTOREPASSWORD=changeit \
  -e REPOSSLENABLED=true \
  -e REPOSSLKEYSTOREPATH=file:/app/certs/keystore.p12 \
  -e REPOSSLKEYSTOREPASSWORD=changeit \
  -p 8080:8080 -p 8443:8443 -p 9090:9090 -p 9443:9443 \
  repsy-os:latest

File permission note

Mounted keystore files must be readable by the container user.

On the host, ensure the file has at least mode 644:

> chmod 644 /host/certs/keystore.p12

>

Production note

For production deployments, use a CA-signed certificate instead of a self-signed one.

Self-signed certificates will cause x509: certificate signed by unknown authority errors

in clients unless the certificate is explicitly trusted.

Installation

Option 1: Docker with H2 (Embedded Database)

No external database required. Suitable for evaluation and development.

docker run -d \
  --name repsy \
  -p 8080:8080 \
  -p 9090:9090 \
  -e ADMININITIALPASSWORD=YourSecurePassword123 \
  -v repsy-data:/app/data \
  repo.repsy.io/repsy/os/repsy:latest

The -v repsy-data:/app/data flag persists the H2 database across container restarts. Setting STORAGEBASEPATH=/app/data/storage ensures artifact file storage is also kept inside the same volume. Without it, artifacts default to ~/.repsy on the host and are not covered by the volume mount.

Option 2: Docker with PostgreSQL

# 1. Create a shared network
docker network create repsy-network
2. Start PostgreSQL
docker run -d \
  --name repsy-postgres \
  --network repsy-network \
  -e POSTGRES_DB=repsy \
  -e POSTGRES_USER=repsy \
  -e POSTGRES_PASSWORD=repsy123 \
  -p 5432:5432 \
  postgres:18
3. Start Repsy
docker run -d \
  --name repsy \
  --network repsy-network \
  -p 8080:8080 \
  -p 9090:9090 \
  -e DB_URL=jdbc:postgresql://repsy-postgres:5432/repsy \
  -e DB_USERNAME=repsy \
  -e DB_PASSWORD=repsy123 \
  -e ADMININITIALPASSWORD=YourSecurePassword123 \
  repo.repsy.io/repsy/os/repsy:latest

Option 3: Docker Compose with PostgreSQL

services:
  postgres:
    container_name: repsy-postgres
    hostname: repsy-postgres
    image: postgres:18
    environment:
      - POSTGRES_DB=repsy
      - POSTGRES_USER=repsy
      - POSTGRES_PASSWORD=repsy123
    ports:
      - "5432:5432"
    networks:
      - repsy-network
repsy:     container_name: repsy     image: repo.repsy.io/repsy/os/repsy:latest     depends_on:       - postgres     ports:       - "8080:8080"       - "9090:9090"     environment:       - DB_URL=jdbc:postgresql://repsy-postgres:5432/repsy       - DB_USERNAME=repsy       - DB_PASSWORD=repsy123       - ADMININITIALPASSWORD=YourSecurePassword123     networks:       - repsy-network
networks:   repsy-network:     driver: bridge

Manual Installation

Prerequisites:

• Java: JDK 25
• Spring Boot: 4.0.5
• PostgreSQL: 18
• Angular: 21
• Maven: 3.9.7 or higher
• Node.js 24.x (>=24.0.0 <25.0.0)

# 1. Build the backend mvn clean install -DskipTests

2. Install frontend dependencies
cd repsy-frontend
pnpm install
cd ..
3. Run with embedded H2 database
cd repsy-backend
mvn spring-boot:run

Access at:

• Frontend (Web UI): http://localhost:4200
• Backend API: http://localhost:8080
• Repository Operations: http://localhost:9090

Configuration

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | ADMININITIALPASSWORD | Initial admin password. Only applied on first startup when no admin exists. | (empty) | | DBURL | JDBC database URL. Defaults to embedded H2. | jdbc:h2:file:/app/data/repsy;MODE=PostgreSQL;DBCLOSEDELAY=-1;DBCLOSEONEXIT=FALSE | | DB_USERNAME | Database username | repsy | | DB_PASSWORD | Database password | repsy123 | | STORAGEBASEPATH | Base directory for artifact file storage. Set to a path inside /app/data (e.g. /app/data/storage) to persist artifacts with a single volume mount. | ~/.repsy | | JWT_SECRET | JWT signing secret. If not set, a random 256-bit secret is generated at startup — all sessions are lost on restart. Set a stable value for production. | (random) | | SERVER_PORT | Repository operations port | 9090 | | API_PORT | Backend API and Frontend web UI port | 8080 | | H2TCPSERVER_ENABLED | Enable H2 TCP server for external database access (development only) | false | | H2TCPSERVER_PORT | H2 TCP server port | 9092 |

Important Notes:

• Admin Username: admin
• Admin Initial Password: Only applied when no admin user exists in the database. After first run, change your password through the application interface.
• JWT_SECRET: Set a stable value via environment variable to avoid session invalidation on restart.

Usage

First Login

• Navigate to http://localhost:8080
• Login with:

- Username: admin - Password: the value you set for ADMININITIALPASSWORD

For detailed information on creating repositories, managing deploy tokens, and using different protocols (Golang, Cargo(Rust), Maven, npm, PyPI, Docker), see the documentation.

Troubleshooting

Common Issues

Port already in use:

# Check what's using port 8080 or 9090 lsof -i :8080 lsof -i :9090

Database connection failed:

# Check if PostgreSQL is running docker ps | grep postgres

Check PostgreSQL logs
docker logs repsy-postgres

Admin user not created:

# Check application logs docker logs repsy

Verify ADMININITIALPASSWORD was set
docker exec repsy env | grep ADMIN

Can't login:

• Verify ADMININITIALPASSWORD was set before the first startup
• Forgot admin password? Reset it by setting hash to NULL in the database:

-- Connect to PostgreSQL   docker exec -it repsy-postgres psql -U repsy -d repsy

-- Reset admin password hash   UPDATE users SET hash = NULL, salt = NULL WHERE role = 'ADMIN';
-- Exit and restart the application   \q   docker restart repsy
-- Check logs for the new random password   docker logs repsy | grep "Admin password"

The application will automatically generate a new random password on next startup.

Logs

docker logs -f repsy
docker logs -f repsy-postgres

Reset Everything

# Stop and remove container
docker rm -f repsy
Remove named volume (if used)
docker volume rm repsy-data
Remove file storage
rm -rf ~/.repsy
Start fresh (H2 example)
docker run -d \
  --name repsy \
  -p 8080:8080 \
  -p 9090:9090 \
  -e ADMININITIALPASSWORD=YourSecurePassword123 \
  -e STORAGEBASEPATH=/app/data/storage \
  -v repsy-data:/app/data \
  repo.repsy.io/repsy/os/repsy:latest

Development

This section is for developers who want to contribute to or modify Repsy.

Prerequisites

• Java: JDK 25
• Spring Boot: 4.0.5
• PostgreSQL: 18
• Angular: 21
• Maven: 3.9.7 or higher
• Node.js 24.x (>=24.0.0 <25.0.0)

Project Structure

repsy/
├── repsy-backend/          # Spring Boot backend
│   ├── src/main/java/         # Java source code
│   ├── src/main/resources/    # Configuration files
│   └── src/test/              # Unit tests
├── repsy-frontend/         # Angular frontend
│   ├── src/app/               # Angular components
│   └── src/assets/            # Static assets
├── libs/                      # Shared libraries
│   ├── protocol-router/       # Protocol routing
│   ├── multiport/             # Multi-port handling
│   └── storage/               # Storage layer
└── repsy-protocols/           # Protocol implementations

Development Setup

# 1. Start PostgreSQL for development
docker run -d \
  --name repsy-postgres \
  -e POSTGRES_DB=repsy \
  -e POSTGRES_USER=repsy \
  -e POSTGRESPASSWORD=repsy123 \
  -p 5432:5432 \
  postgres:18
2. Build backend
mvn clean install -DskipTests
3. Run backend in development mode
cd repsy-backend
mvn spring-boot:run
4. In another terminal, run frontend
cd repsy-frontend
pnpm install
pnpm start

Access development environment:

• Frontend (Web UI): http://localhost:4200 (with hot reload)
• Backend API: http://localhost:8080
• Repository Operations: http://localhost:9090
• To inspect the H2 database directly, enable the TCP server with H2TCPSERVER_ENABLED=true and connect via jdbc:h2:tcp://localhost:9092/~/repsy using a tool like DBeaver or IntelliJ

Building for Production

# Build Docker image (run from repo root)
docker build -f Dockerfile -t repsy:latest .

Code Style

• Java: Follow Google Java Style Guide
• TypeScript/Angular: Follow Angular Style Guide
• Commits: Use conventional commits format

Database Migrations

Migrations are managed with Flyway in src/main/resources/db/migration/.

# File format: V{version}__{description}.sql
Example: V0002_adduser_roles.sql

Contributing

• Fork the repository
• Create feature branch: git checkout -b feature/amazing-feature
• Commit changes: git commit -m 'feat: add amazing feature'
• Push to branch: git push origin feature/amazing-feature
• Open Pull Request

Contribution Guidelines:

• Write tests for new features
• Update documentation
• Follow existing code style
• Keep commits atomic and well-described

License

This project is licensed under the Apache License, Version 2.0 - see the LICENSE.txt file for details.

Support

• Documentation: docs.repsy.io
• Issues: GitHub Issues

---

Developed using Spring Boot and Angular