Reposilite on AWS User Guide

Overview

This image runs Reposilite, a lightweight, high performance and easy to use open source repository manager for Maven and Gradle artifacts, written in Kotlin on the JVM. Reposilite hosts your private Maven repositories, proxies and caches remote repositories such as Maven Central, and exposes a modern web dashboard, a REST API and access token based authentication, all from a single self contained service.

Reposilite runs from its official standalone JAR on a private Eclipse Temurin 21 JRE and runs as a dedicated unprivileged reposilite system account under a systemd service that starts it on boot and restarts it on failure. The working directory lives at /var/lib/reposilite, a dedicated, independently resizable EBS data volume, and holds the configuration, the SQLite token and statistics database and the hosted artifacts.

Reposilite provides its own access token authentication, so the JAR binds to the loopback interface only and is never exposed directly. An nginx reverse proxy publishes the web dashboard, the Maven and Gradle repositories and the REST API on port 80, with WebSocket support for the live management console. An administrative manager token is generated on the first boot of every deployed instance, so two instances launched from the same Amazon Machine Image never share a token. It is written to /root/reposilite-aws-credentials.txt with mode 0600 so that only the root user can read it.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network and port 80 for the dashboard, repositories and REST API
• The AWS CLI (version 2) installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for Reposilite. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of t3.medium or larger. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that opens port 22 from your management network and port 80 for the dashboard and repositories. Leave the root volume at the default size or larger.

Select Launch instance. First boot initialisation, which generates the admin manager token and starts Reposilite, takes up to a minute after the instance state becomes Running and the status checks pass.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg Reposilite Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens ports 22 and 80 as described above.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type t3.medium \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=reposilite}]'

When the instance reaches the Running state and its status checks pass, note its public IP address or DNS name from the EC2 console or with aws ec2 describe-instances.

Step 3: Connect to Your Instance

Connect over SSH using your key pair and the login user for your operating system variant.

ssh -i <key-name>.pem ubuntu@<public-ip>

Step 4: Retrieve the Admin Manager Token

The Reposilite admin token is unique to your instance and was generated on first boot. Read it as root:

sudo cat /root/reposilite-aws-credentials.txt

The file lists the dashboard URL, the admin token name (admin) and the generated token secret, along with example REST and Maven usage. The admin token is a manager token, meaning it has full administrative access. Keep this token somewhere safe.

Step 5: Sign In to the Web Dashboard

The Reposilite web dashboard is served on port 80 by nginx. In a browser, go to:

http://<instance-public-ip>/

Select Sign in in the top right, then enter the token name admin and the generated token secret. After signing in you see the management tabs (Overview, Dashboard, Console and Settings) and the hosted repositories.

The Overview tab browses the hosted repositories. Reposilite ships with a releases, a snapshots and a private repository by default. Open a repository to browse its group, artifact and version tree.

The Settings tab lets a manager configure authentication, the frontend, Maven behaviour, statistics and the web server, with changes applied through the live console.

Step 6: Confirm Reposilite Is Running

Over SSH, confirm Reposilite and the nginx proxy are active and that the ports are listening:

sudo systemctl is-active reposilite nginx
sudo ss -tlnp | grep -E ':(80|8080) '

You should see both services reported as active, Reposilite listening on 127.0.0.1:8080 (loopback only), and nginx listening on port 80.

Step 7: Verify the Token with the REST API

Reposilite exposes a REST API on port 80 behind the same access token authentication. Verify your manager token and inspect its permissions with the auth/me endpoint. On the instance you can read the token from the credentials file and call the API over loopback:

TOKEN=$(sudo grep '^reposilite.admin.token=' /root/reposilite-aws-credentials.txt | cut -d= -f2-)
curl -s -u "admin:${TOKEN}" http://127.0.0.1/api/auth/me

The response is a JSON document listing the token name, its manager permission and any per route permissions. From outside the instance, send the same request to http://<instance-public-ip>/api/auth/me with HTTP Basic user admin and your token.

Step 8: Publish and Resolve an Artifact

Reposilite serves the standard Maven layout, so you can publish and resolve artifacts with plain HTTP. The following loopback example, run on the instance, publishes a small file into the default releases repository and resolves it back, proving the repository is live:

TOKEN=$(sudo grep '^reposilite.admin.token=' /root/reposilite-aws-credentials.txt | cut -d= -f2-)
printf 'hello from reposilite\n' > /tmp/example.txt
curl -s -u "admin:${TOKEN}" --upload-file /tmp/example.txt \
  http://127.0.0.1/releases/com/example/demo/1.0.0/demo-1.0.0.txt
curl -s -u "admin:${TOKEN}" \
  http://127.0.0.1/releases/com/example/demo/1.0.0/demo-1.0.0.txt

The upload returns the deployed path and the download returns the file contents. From your build machines, target http://<instance-public-ip>/releases/... with the same token.

Step 9: Configure Maven

To resolve and deploy artifacts from Maven, add a <server> entry to your ~/.m2/settings.xml using the token name as the username and the token secret as the password, then reference the repository in your project. The dashboard Repository details panel generates the exact snippets for Maven, Gradle Kotlin, Gradle Groovy and SBT. A typical settings.xml server entry looks like this, with <your-token> replaced by the token secret:

<settings>
  <servers>
    <server>
      <id>reposilite-releases</id>
      <username>admin</username>
      <password><your-token></password>
    </server>
  </servers>
</settings>

In your project pom.xml, point the repository and distribution management at http://<instance-public-ip>/releases using the matching <id>. For day to day use, issue a dedicated read or read and write token per developer or CI pipeline from the dashboard Console tab rather than sharing the admin manager token.

Step 10: Issue Access Tokens for Your Team

The admin manager token is for administration. Create scoped tokens for your developers and CI from the dashboard Console tab, which drives the same remote command line as the server console. Use the token-generate command with a name and a permission shortcut (for example r for read or w for write), and optionally restrict the token to a route. Reposilite returns the generated secret once, so record it immediately. Manager (m) tokens have full access and should be reserved for administrators.

Step 11: Proxy Remote Repositories

Reposilite can proxy and cache remote repositories such as Maven Central so your builds pull through a single endpoint. In the Settings tab, edit the Maven configuration to add proxied hosts to a repository, then point your build tools at your Reposilite repository instead of the upstream. Cached artifacts are stored under the working directory on the data volume.

Step 12: The Data Volume

The Reposilite working directory lives on a dedicated EBS volume mounted at /var/lib/reposilite. This keeps the configuration, the token database and the hosted artifacts off the operating system disk and lets you resize or snapshot it independently. Confirm the mount with:

df -h /var/lib/reposilite

To grow the store, expand the EBS volume in the AWS console, then grow the filesystem on the instance with sudo resize2fs on the underlying device.

Step 13: Enable HTTPS

The dashboard, repositories and REST API are served over plain HTTP on port 80 by nginx. For production use, place them behind TLS. Obtain a certificate for your domain (for example with a managed certificate on an Application Load Balancer in front of the instance, or with Certbot installed on the instance), then configure nginx to listen on 443 with your certificate and proxy to 127.0.0.1:8080 exactly as the bundled site does for port 80, keeping the WebSocket upgrade headers in place. Restrict the security group so ports 80 and 443 are reachable only from the networks that publish and resolve artifacts.

Step 14: Backup and Maintenance

Back up Reposilite by snapshotting the /var/lib/reposilite EBS volume, which captures the configuration, the token database and every hosted artifact. Apply operating system security updates with sudo apt-get update && sudo apt-get upgrade and reboot when a new kernel is installed; Reposilite and nginx start automatically on boot.

Support

This image is published and supported by cloudimg. Support covers deployment, repository and proxy configuration, access token and permission management, Maven and Gradle client setup, storage and TLS tuning. Contact cloudimg through the support channel listed on the AWS Marketplace listing.

All product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.