Skip to content

Raw Integration Guide

OrbitRepos provides a versatile Raw format handler for storing arbitrary binary files. This is ideal for artifacts that don't fit into specific package manager formats, such as ISO images, compiled binaries, build logs, or static assets.

Overview

The Raw handler provides a simple, path-based interface for managing files using standard HTTP methods. Key features include:

  • Arbitrary Directory Structures: Organize your files in any hierarchy using URL paths.
  • RESTful API: Use standard PUT, GET, and DELETE requests for artifact lifecycle management.
  • MIME Type Detection: Automatically detects and serves the correct Content-Type for known file extensions.
  • Directory Listings: Browse repository contents via the Web UI or JSON API.
  • Proxy Support: Cache files from any upstream HTTP(S) server (e.g., GitHub Releases, S3 buckets).

The Raw handler is served at the /raw/{repoName}/ route.

Prerequisites

Before you begin, ensure you have the following:

  • A tool for making HTTP requests, such as curl or wget.
  • An active OrbitRepos instance. See the Quick Start for setup instructions.
  • Network access to http://localhost:8080.

Create a Repository

You can create a Raw repository via the Web UI or the Management API.

  1. Log in to OrbitRepos (default: admin/admin).
  2. Navigate to Repositories > Create Repository.
  3. Select Raw as the format.
  4. Choose a type: hosted, proxy, or group.
  5. Name it my-binaries (for this guide).
  6. Click Create.
curl -u admin:admin -X POST http://localhost:8080/api/v1/repositories \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-binaries",
    "format": "raw",
    "type": "hosted"
  }'

Push / Publish Artifacts

To upload artifacts to a hosted repository, use an HTTP PUT request. OrbitRepos will create any necessary parent directories automatically.

1. Simple File Upload

Upload a local file to the root of the repository: 

curl -u admin:admin -T my-app.exe http://localhost:8080/raw/my-binaries/my-app.exe

2. Nested Directory Upload

Upload a file to a specific path: 

curl -u admin:admin -T build.log http://localhost:8080/raw/my-binaries/logs/2026/02/13/build.log

Overwriting

By default, PUT requests will overwrite existing files at the same path. Ensure your CI/CD pipelines use unique paths (e.g., including build numbers or timestamps) if you need to preserve history.

Pull / Install Artifacts

Artifacts can be downloaded using standard HTTP GET requests or browsed via the Web UI.

1. Download via CURL

curl -u admin:admin -O http://localhost:8080/raw/my-binaries/my-app.exe

2. Download via Wget

wget --user admin --password admin http://localhost:8080/raw/my-binaries/logs/2026/02/13/build.log

3. Directory Listing

To list the contents of a directory, request the path ending with a slash. OrbitRepos returns a JSON object containing file and directory metadata. 

curl -u admin:admin http://localhost:8080/raw/my-binaries/logs/

MIME Types

OrbitRepos identifies the file type based on the extension (e.g., .pdf, .zip, .html) and sets the Content-Type header accordingly, ensuring browsers and tools handle the download correctly.

Proxy Setup

A proxy repository allows you to cache files from an external HTTP server locally. This is useful for mirroring static assets or third-party binaries.

  1. Create a new repository with type proxy.
  2. Set the Remote URL to the base URL of the upstream server (e.g., https://github.com/vanlongme/OrbitRepos/releases/download/v1.0.0/).
  3. Access the file through OrbitRepos: 
    curl -O http://localhost:8080/raw/my-proxy-repo/orbitrepo-linux-amd64
  4. OrbitRepos will fetch the file from GitHub on the first request, store it in the local cache, and serve subsequent requests directly from storage.

Troubleshooting

Issue Cause Resolution
401 Unauthorized Missing or incorrect credentials. Verify your username and password or API token.
404 Not Found File path or repository name is incorrect. Verify the path in the Web UI. Ensure the repository format is raw.
403 Forbidden Insufficient permissions for the user. Check the user's role in Security > Users. Hosted repos require deployer or higher.
Upload Failed Network timeout or disk space issue. Check the OrbitRepos server logs and available storage space.
Incorrect Content-Type File extension not recognized. OrbitRepos uses a standard MIME mapping. Ensure the file has a common extension.

Path Security

Avoid using reserved characters or path traversal sequences (like ../) in your file names. OrbitRepos sanitizes paths, but it is best practice to use alphanumeric characters, hyphens, and underscores.