Getting started

This chapter takes you from nothing to a repository running on your own machine in a few minutes. You start the server from its Docker image, sign in to the web console, create a repository for Maven and one for npm, issue a key for your build tools, and publish and resolve an artifact with each. Everything later in this section builds on what is here.

Run the image

You need Docker, and nothing else. The server keeps everything it holds - artifacts, indexes, settings, keys - in one folder, so give that folder a volume of its own and tell the server where it is:

docker run -d --name jenesis -p 8080:8080 \
  -v jenesis-data:/data -e JENREPO_FILESYSTEM_ROOT=/data \
  jenesisbuild/jenesis-repository

JENREPO_FILESYSTEM_ROOT is the one setting a start needs. Without it the server refuses to start and names the setting, rather than inventing a folder that disappears with the container - or, worse, one a deployment meant for an object store would quietly fill.

The server listens on port 8080 and answers there for everything: the console, the repository's clients and the API. When it has started, and nobody can sign in to it yet, it prints a welcome with a one-time key:

docker logs jenesis

==============================================================================

   WELCOME TO JENESIS REPOSITORY

   Nobody can sign in yet, so here is a one-time key to get started:

       jfr_…

   Open http://localhost:8080 (or this server's address), choose
   "Sign in with a key" and paste it. The setup guide opens after you sign in.

   The key works until 2026-09-25 13:00 UTC, and only until an administrator is set up.
   If it runs out first, restart the server and it prints a new one.

==============================================================================

The key is shown once and stored only as a hash. It stops working after an hour, or as soon as the deployment has an administrator, whichever comes first; a restart of a deployment that still has none prints a new one.

Sign in

Open http://localhost:8080 in a browser. The sign-in page offers Sign in with a key; choose it and paste the key from the log.

The sign-in lands on First-run setup, a wizard through the decisions a new deployment should make. Its first step is the one to take now: name a real administrator, because the one-time key is about to stop working. It comes filled in with keylogin/admin, so applying the setup makes that administrator and shows its login key once, on the screen you land on - copy it, because only its hash is kept, and sign in with it from then on. The step can instead sign you in with a GitHub OAuth app and make the identity GitHub returns the administrator, as Settings describes. On a deployment with no repository yet, the first page also offers to load a demo that fills the console with sample repositories and packages.

The steps after it - which advisory feeds to consult, what the gate does with a vulnerable or malicious package, how long repositories keep what they hold - each show the current value, and Next keeps it unless you change it. The last step reviews every choice, and Apply setup saves them together; nothing is saved before that, and every answer can be changed later. Use defaults takes you into the console with nothing changed, and the wizard stays reachable as Settings → First-run setup.

The console is laid out in two levels. Across the top are its sections - Repositories, Build cache, Access, Operations and Settings - and down the left side are the pages of the section you are in. Finding your way around walks through them.

Create the repositories

A repository holds one type of artifact, and it is created before anything is published into it - a publish into a repository that does not exist is refused with 404. Create two:

1. Open Repositories → Current repositories and press New repository.
2. Enter the name libraries, choose the format maven, and press Next. The steps that follow ask how long the repository keeps what it holds and where it fetches from; leave them empty for now, and on the review press Create repository.
3. Do the same with the name npm and the format npm.

Every URL names the tenant and then the repository: a new deployment serves the tenant releases, so these two answer at /repository/releases/libraries/ and /repository/releases/npm/. A script creates a repository with a PUT of that URL naming the type, or with jenrepo repos create libraries maven from the command line - Repositories shows how - and Connecting your build tools lists the other types.

Issue a key for your build tools

Build tools do not sign in; they present a key. Issue one in the console:

1. Open Access → Credentials.
2. Under New credential, give it a label such as laptop and press Generate credential.
3. The credential's page opens with the key shown once - copy it now. Only a hash of it is stored, so a key that is lost is re-issued, never recovered.
4. Under Grants, enter * as the scope, choose the role deploy, and press Grant.

A new key holds no rights until you grant some. * with deploy lets it read and publish everywhere; the Access chapter covers narrower grants, expiry and rotation.

The rest of this chapter uses the key as $KEY:

KEY=jenk_releases.…

Publish and resolve with Maven

A Maven repository keeps Maven's own maven/ segment in its URLs, so libraries answers Maven at /repository/releases/libraries/maven/. Put the key in ~/.m2/settings.xml as the password of a server entry - the user name is not checked:

<settings>
  <servers>
    <server>
      <id>jenesis</id>
      <username>jenesis</username>
      <password>jenk_releases.…</password>
    </server>
  </servers>
</settings>

Publish a jar, then resolve it back:

mvn deploy:deploy-file -Dfile=app.jar \
  -DgroupId=com.example -DartifactId=app -Dversion=1.0 -Dpackaging=jar \
  -DrepositoryId=jenesis -Durl=http://localhost:8080/repository/releases/libraries/maven/

mvn dependency:get -Dartifact=com.example:app:1.0 \
  -DremoteRepositories=jenesis::default::http://localhost:8080/repository/releases/libraries/maven/

In a project, the same URL goes into <distributionManagement> to publish and into <repositories> to resolve, each with the jenesis id so Maven finds the credentials.

Publish and resolve with npm

The npm repository is the registry at /repository/releases/npm/. Point npm at it and give it the key as a token:

npm config set registry http://localhost:8080/repository/releases/npm/
npm config set //localhost:8080/repository/releases/npm/:_authToken "$KEY"

npm publish                  # from a package's folder
npm install my-package       # from anywhere else

Every other client follows the same pattern - a repository of its type, its URL under /repository/releases/, and the key as a password or a token. Connecting your build tools lists them all.

See it in the console

Back in the console, Repositories lists libraries and npm. Open libraries: the overview says what it is and how it is routed, and the pages on the left take you into it - Browse & search walks the stored files, and Quarantine, Vulnerabilities and their neighbours show what the gate decided about each artifact on its way in.

Stopping, upgrading and backing up

The container holds nothing the volume does not, so it can be replaced at will:

docker rm -f jenesis
docker pull jenesisbuild/jenesis-repository
docker run -d --name jenesis -p 8080:8080 -v jenesis-data:/data …     # the same settings as before

Backing up the volume backs up the repository, and copying it moves the repository. The image is also published with a version tag beside latest, and pinning one keeps an upgrade a deliberate act.