Skip to content

FAQ & Troubleshooting

This page provides answers to frequently asked questions and solutions for common issues encountered when setting up or operating OrbitRepos.

General FAQ

What is OrbitRepos? How does it compare to Artifactory or Nexus?

OrbitRepos is a lightweight, high-performance, self-hosted artifact repository manager. It is designed to be the single source of truth for your software packages, including Docker images, Maven artifacts, npm packages, and more.

Compared to heavyweight solutions like JFrog Artifactory or Sonatype Nexus:

  • Footprint: OrbitRepos is distributed as a single Go binary with an embedded React UI, making it significantly lighter and faster to start.
  • Simplicity: It focuses on the most essential features (RBAC, OIDC, S3 storage, Proxy/Group repos) without the complexity of enterprise bloat.
  • Modern Stack: Built with Go 1.24 and React, it leverages modern performance and security standards.
  • Ease of Use: Configuration is straightforward via a single YAML file or environment variables.
Which artifact formats are supported?

OrbitRepos supports a wide range of modern package formats:

  • Container: Docker Registry v2 (push, pull, tagging).
  • Package Managers: Maven (Java), npm (JavaScript), PyPI (Python), NuGet (.NET), Go Modules, Helm (Kubernetes), and APT (Debian/Ubuntu).
  • Generic: Raw binary storage for any file type (e.g., ISOs, ZIPs, compiled binaries).
How do I integrate OrbitRepos into my CI/CD pipeline?

OrbitRepos is designed for automation. You can use:

  • API Tokens: Create long-lived tokens prefixed with orb_ for use in GitHub Actions, GitLab CI, Jenkins, etc.
  • Basic Auth: Use your username and password (or API token as the password) with standard tools like docker login, npm login, or mvn deploy.
  • REST API: All functionality available in the UI is also available via a stable REST API.
What are the system requirements?

OrbitRepos is highly efficient:

  • Runtime: A single binary for Linux, macOS, or Windows (via Docker).
  • Database: PostgreSQL 16+ is required for metadata storage.
  • Storage: Either a local filesystem directory or an S3-compatible bucket (AWS S3, MinIO, Google Cloud Storage, etc.).
  • Memory/CPU: Minimum 512MB RAM and 0.5 CPU core for small teams; scales linearly with traffic.
How do I upgrade OrbitRepos to a newer version?

Upgrading is simple:

  1. Back up your PostgreSQL database and storage backend.
  2. Replace the old binary with the new one (or update your Docker image tag).
  3. Restart the service.

OrbitRepos automatically handles database schema migrations on startup. If a migration fails, the server will log the error and stop to prevent data corruption.

Is OrbitRepos production-ready?

Yes! OrbitRepos includes several enterprise-grade features for production use:

  • High Availability: Can be run in a cluster behind a load balancer (state is stored in Postgres and S3).
  • Security: Robust RBAC model, LDAP/OIDC integration, and secure JWT handling.
  • Performance: Optimized for high-concurrency artifact streaming.
  • Important: Always change the default ORBITREPO_AUTH_JWT_SECRET and ORBITREPO_DATABASE_PASSWORD before deploying to production.
What is the license for OrbitRepos?

OrbitRepos is released under the Apache License 2.0. This is a permissive license that allows for commercial use, modification, and distribution.

How can I report bugs or request new features?

We welcome community feedback! Please visit our GitHub Repository and open an issue. Provide as much detail as possible, including logs and steps to reproduce for bug reports.

How is data persisted in OrbitRepos?

OrbitRepos uses a two-tier persistence model:

  1. Metadata: All repository configurations, user accounts, RBAC settings, and artifact metadata (names, versions, hashes, upload times) are stored in a PostgreSQL database.
  2. Binary Blobs: The actual artifact files (Docker layers, JAR files, npm tarballs) are stored in the Storage Backend. You can choose between:
    • Filesystem: High-performance local storage (ideal for single-node setups).
    • S3-Compatible: Scalable object storage (AWS S3, MinIO, etc.) for high availability and durability.
Can I limit storage usage or set retention policies?

Yes. OrbitRepos includes a background cleanup scheduler. You can define retention policies based on:

  • Max Versions: Keep only the last $N$ versions of an artifact.
  • Max Age: Delete artifacts older than $X$ days.
  • Pattern Matching: Apply policies only to specific repositories or artifact paths.

The cleanup task runs every hour by default (configurable via cleanup.schedule_interval) and removes both the metadata from PostgreSQL and the corresponding files from your storage backend.

Does OrbitRepos support proxying private external registries?

Yes. Proxy repositories can be configured to point to any external registry. If the remote registry requires authentication, you can configure the remote credentials (username/password or token) within the proxy repository settings. OrbitRepos will securely store these credentials and use them when fetching artifacts on behalf of your users.

Is there an official OrbitRepos CLI?

While there is no dedicated orbitrepo CLI tool yet, OrbitRepos is designed to be compatible with existing package manager CLIs (like docker, mvn, npm, pip). For management tasks, everything is exposed via a standard REST API, which can be easily consumed using curl or any HTTP client.

Troubleshooting

Connectivity & Network Issues

Cannot connect to OrbitRepos

If you are unable to reach the OrbitRepos web UI or API: 1. Check the Host/Port: Ensure server.host (default 0.0.0.0) and server.port (default 8080) are correctly configured and not blocked by a local firewall or security group. 2. Verify Logs: Look at the server logs for any "bind: address already in use" errors, which indicate another service is using the same port. 3. Network Path: If running in Docker, ensure you have mapped the ports correctly (e.g., -p 8080:8080) and that your Docker bridge network is healthy. 4. Reverse Proxy Config: If using Nginx, ensure your proxy_pass points to the correct container IP or service name.

Slow download/upload speeds

  • Network Latency: Check the latency between your CI runners and the OrbitRepos server.
  • Storage Throughput: If using S3, ensure your server has sufficient egress bandwidth. If using Filesystem, check for disk I/O bottlenecks.
  • Proxy Buffer: If using a reverse proxy, ensure it isn't buffering the entire request before passing it to OrbitRepos. For Nginx, consider setting proxy_buffering off; for large artifact routes.

Artifact Upload/Download Failures

Docker push/pull failures

Common issues with the Docker Registry v2 implementation: * Authentication: Ensure you have run docker login <your-registry-url> with valid credentials or an API token. * Large Images: If pushing large layers fails halfway, check server.max_request_body (default 10GB) and server.write_timeout (default 300s). * HTTPS Requirement: By default, the Docker CLI requires HTTPS. If running OrbitRepos over plain HTTP, you must add the domain to insecure-registries in your daemon.json. * Reverse Proxy: If using Nginx or Traefik, ensure client_max_body_size is set to 0 (unlimited) or a sufficiently high value.

Large file timeouts (504 Gateway Timeout)

By default, OrbitRepos has a 5-minute (300s) write timeout for HTTP requests. Extremely large artifacts (e.g., several gigabytes) or slow network connections may exceed this limit. * Solution: Increase ORBITREPO_SERVER_WRITE_TIMEOUT in your environment or server.write_timeout in your YAML config. * Upstream Timeouts: If you are using a load balancer (AWS ALB, Nginx, etc.), you must also increase the timeout on that layer to match or exceed the OrbitRepos timeout.

Storage Backend Issues

S3 storage issues

  • Bucket Existence: OrbitRepos does not create buckets. Ensure the bucket specified in storage.s3.bucket exists before starting the server.
  • Permissions: The IAM user or Access Key must have full s3:* permissions on the bucket, specifically PutObject, GetObject, DeleteObject, and ListBucket.
  • MinIO Configuration: For MinIO or other local S3 clones, you must set storage.s3.use_path_style to true to avoid DNS-based bucket routing issues.
  • Endpoints: For AWS S3, leave the endpoint empty to use standard AWS SDK discovery. For MinIO, include the protocol and port (e.g., http://minio:9000).

Cleanup policies not running as expected

If your artifacts are not being deleted by retention policies: 1. Check Scheduler Status: Ensure cleanup.enabled is true. 2. Verify Interval: The default interval is 60 minutes. It may take up to an hour for a new policy to trigger its first run. 3. Check Logs: Search the logs for "Cleanup manager started" and any subsequent error messages. 4. Metadata Sync: Retention policies only act on artifacts tracked in the database. If you manually uploaded files to S3 without going through the OrbitRepos API, the cleanup scheduler won't know they exist.

Authentication & Identity Providers

OIDC/LDAP login failures

  • Issuer URL: For OIDC, the issuer_url must be a valid HTTPS URL reachable by the OrbitRepos server.
  • Browser Redirects: If OrbitRepos is running inside a Docker network but accessed via localhost, you likely need to set auth.oidc.browser_issuer_url to the public address of your OIDC provider.
  • LDAP Filter: Ensure auth.ldap.user_filter (default (uid=%s)) matches your directory schema. For Active Directory, this is usually (sAMAccountName=%s).
  • Group Sync: If group sync is enabled but users aren't getting the right roles, verify that the OIDC groups_claim matches the claim name in your provider's JWT.
  • Debug Logs: Set ORBITREPO_LOG_LEVEL=debug to see the full handshake and the specific error returned by the identity provider.

Database & Performance

Database connection errors

  • PostgreSQL Version: OrbitRepos is tested against PostgreSQL 16. Older versions may lack required features.
  • SSL Mode: If your Postgres provider (e.g., AWS RDS, Azure Database) requires encrypted connections, set database.ssl_mode to require.
  • Connection Pool Exhaustion: If the UI becomes unresponsive, you may be hitting the database.max_open_conns limit (default 25). Monitor your database's max_connections and adjust accordingly.

Proxy repository not caching artifacts

  • Cache TTL: Check the proxy.cache_ttl setting. Artifacts are cached for 24 hours by default.
  • Outbound Connectivity: Ensure OrbitRepos has outbound internet access to reach the remote registry.
  • Disk/Storage Full: If your storage backend is full, OrbitRepos will fall back to proxying without caching (streaming directly from remote to user).
  • Logs: Check for "failed to cache artifact" warnings in the server logs.