Web UI

Registrator Web UI

Usage (For Package Maintainers)

This section is for people who want to use Registrator to register their packages.

Before Registering

Who Can Register a Package?

If the package is owned by an individual, then you must be that individual, or a collaborator on the repository. If the package is owned by an organization/group, then you must be a member of that organization.

Validating (Julia)Project.toml

Your package must have a JuliaProject.toml or Project.toml file at the repository root. It should contain at least three keys:

Registering

Once you've prepared your repository, using Registrator is simple.

  1. The first thing to do is to identify yourself as someone who can register your package. At the homepage of the site, you'll be greeted by links to log in to either GitHub or GitLab. If you're registering a GitHub package, then log into GitHub, and likewise for GitLab.

  2. Once authenticated, you'll see a text box to input the URL to your package repository. Do so, then press "Submit". The page might seem unresponsive for a while, but it'll get back to you within 10 seconds or so.

  3. If everything worked out, then you should see a link to a new pull request in the registry! Sit back and let a registry maintainer complete the process for you. Otherwise, you'll see a (hopefully) informative reason for failure.

<!โ€“ TODO: Screenshots. โ€“>

Setup (For Registry Maintainers)

This section is for people who want to host an instance of Registrator for their own registry.

Provider Setup

Here, the term $PROVIDER indicates the provider of your registry repository. In most cases, that will be GitHub, or perhaps GitLab.

You will need:

The OAuth providers currently supported are GitHub and GitLab. You can choose to support one or both (or none, but that wouldn't be very useful).

For each provider that you support, you will need:

Git Setup

Git must be installed on the host computer. Additionally, it must be configured so that it can push to the registry, preferably as the user you just created. You should make sure that you've set up any credential handling such as SSH keys.

Configuration

Registrator configuration is done with a config file. Some of its values are required, and some are optional. It's important to note that optional values must be omitted or commented out when not in use.

[web] Section

Required
Optional

[web.git{hub,lab}] Section

If you want to disable a provider, simply omit its section. For example, to support GitHub packages but not GitLab packages, only provide a [web.github] section.

Required
Optional

Adding Extra Providers

In almost all cases, you shouldn't need to do this. The only real use case is when your registry is on a self-hosted GitHub or GitLab instance, and you also want to allow registering of packages from the public instance of that provider. The only two providers supported are GitHub and GitLab. If you do want to do this, then you should set web.extra_providers as mentioned above. The file should look like this:

PROVIDERS["mygithub"] = Provider(;
    name="PrivateGitHub",
    client=GitHubAPI(;
        url="https://api.github.mysite.com",
        token=Token("my_github_token"),
    ),
    client_id="my_oauth_app_client_id",
    client_secret="my_oauth_app_client_secret",
    auth_url="https://github.mysite.com/oauth/authorize",
    token_url="https://github.mysite.com/oauth/token",
    scope="public_repo",
)

PROVIDERS["mygitlab"] = Provider(;
    name="PrivateGitLab",
    client=GitLabAPI(;
        url="https://gitlab.mysite.com/api/v4",
        token=PersonalAccessToken("my_gitlab_token"),
    ),
    client_id="my_oauth_app_client_id",
    client_secret="my_oauth_app_client_secret",
    auth_url="https://gitlab.mysite.com/oauth/authorize",
    token_url="https://gitlab.mysite.com/oauth/token",
    scope="read_user",
    include_state=false,
    token_type=OAuth2Token,
)

The OAuth2 application info and URLs are covered above. When setting your OAuth2 application's callback URL, make sure that it ends with ?provider=$PROVIDER, where $PROVIDER is mygithub for the GitHub example above.

Running the Server

To run the server, first add Registrator to your Julia environment. Then, make sure that your configuration file is written correctly. The following code will start the server:

using Registrator
Registrator.WebUI.main()

A directory called registries will be created, which contains your registry. It's not important to keep it intact, as it is synchronized before registering any package.

Basic Recipe: Public Registry

Here's a general case of hosting a registry on GitHub and allowing package registrations from both GitHub and GitLab. The registry will be owned by RegistryOwner and the name will be MyRegistry. The web server will be hosted at https://myregistrator.com, and run on port 4000.

The first thing we'll do is set up a config.toml file with some information we already have.

Note that in this and any following examples, the section names (i.e. [web]) will always be included for clarity. However, they should only appear once in the final file.

[web]
ip = "0.0.0.0"
port = 4000
server_url = "https://myregistrator.com"
registry_url = "https://github.com/RegistryOwner/MyRegistry"

Next, we create the GitHub and GitLab users and API keys, and save those API keys:

[web.github]
token = "abc..."

[web.gitlab]
token = "abc..."

Next, create OAuth2 applications for both of them. The callback URLs will be https://myregistrator.com/callback?provider=github and https://myregistrator.com/callback?provider=gitlab. Add the client IDs and secrets to our file:

[web.github]
client_id = "abc..."
client_secret = "abc..."

[web.gitlab]
client_id = "abc..."
client_secret = "abc..."

Now let's configure Git and set up SSH authentication to GitHub.

Configure name and email by running these commands:

git config --global user.name Registrator
git config --global user.email registrator@myregistrator.com

Then, create an SSH key with ssh-keygen, and hit enter a few times to generate a key. Now go to GitHub user settings and add the public key to your new user.

To actually use this key, we'll set the clone URL for our registry in .env:

[web]
registry_clone_url = "git@github.com:RegistryOwner/MyRegistry.git"

Our file is finished, and looks like this:

[web]
ip = "0.0.0.0"
port = 4000
server_url = "https://myregistrator.com"
registry_url = "https://github.com/RegistryOwner/MyRegistry"
registry_clone_url = "git@github.com:RegistryOwner/MyRegistry.git"

[web.github]
token = "abc..."
client_id = "abc..."
client_secret = "abc..."

[web.gitlab]
token = "abc..."
client_id = "abc..."
client_secret = "abc..."

Now that this is done, we're ready to run the server. Since our config file is at the default location (config.toml), we don't need to pass any arguments.

# Instalation: Just do this once.
julia -e '
    using Pkg;
    Pkg.add("https://github.com/JuliaRegistries/Registrator.jl")'

# Run this every time.
julia -e '
    using Registrator;
    Registrator.WebUI.main()'

Basic Recipe: Private Registry

This guide will be almost identical to the one above, but we'll set up a private, self-hosted registry and only allow packages from that provider.

Let's assume we're running a GitLab instance at https://git.corp.com, and our repo is at Registries/General. We want to host our instance at https://registrator.corp.com.

First, let's again start off with a TOML file, but this time at myconfig.toml:

[web]
registry_provider = "gitlab"

[web.gitlab]
api_url = "https://git.corp.com/api/v4"
auth_url = "https://git.corp.com/oauth/authorize"
token_url = "https://git.corp.com/oauth/token"
registry_url = "https://git.corp.com/Registries/General"
server_url = "https://registrator.corp.com"

As you can see, We had to set a few URLs manually. Additionally, we set registry_provider = "gitlab" because the string "gitlab" does not occur in our registry's URL.

Next, we create our user, API key, and OAuth application. Make sure to enable the read_user scope, and to set the callback URL to https://registrator.corp.com/callback?provider=gitlab.

Add our credentials to the file:

[web.gitlab]
token = "abc..."
client_id = "abc..."
client_secret = "abc..."

We'll do the same Git configuration as before, and set our clone URL appropriately:

[web]
registry_clone_url = "git@git.corp.com:Registries/General"

And then we're ready. We can run it in the same way as before, but passing our non-default config path:

julia -e '
    using Registrator;
    Registrator.WebUI.main("myconfig.toml")'