Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


⚠️ MiniRepo is deprecated in favour of an offical self-hosting solution from the Hex team, mix hex.registry build (available from Hex v0.21+).

MiniRepo allows self-hosting of Hex packages.


  • Pluggable storage. MiniRepo ships with following adapters:

    • Local filesystem

    • S3

  • Mirroring

  • Publishing packages via HTTP API

  • Hosting of multiple repositories and mirrors

    MiniRepo exposes following URLs for API and repository access:

    • http://some_url/api/

    • http://some_url/repos/

Learn more about Hex specifications here.


Clone and install dependencies:

git clone
cd mini_repo
mix deps.get

Start a development server:

iex -S mix

By default, the development server is configured with two repositories:

  • test_repo is a custom repository

  • hexpm_mirror is a mirror of the official repository, configured to only fetch package decimal.

Both repositories are configured to store files locally. See config/dev.exs for more information.

Make sure to also read "Deployment with releases" section below.


Once you have the MiniRepo server running, here is how you can use it with Mix or Rebar3.

Usage with Mix

Let's create a new package and publish it to our test_repo repository:

$ mix new foo
$ cd foo

Make following changes to that package's mix.exs:

  def project() do
      app: :foo,
      version: "0.1.0",
      elixir: "~> 1.9",
      start_permanent: Mix.env() == :prod,
      deps: deps(),
      description: "Some description",
      package: package(),
      hex: hex(),

  defp deps() do

  defp package() do
      licenses: ["Apache-2.0"],
      links: %{}

  defp hex() do
      api_url: "http://localhost:4000/api/repos/test_repo",
      # make sure to change it, see `auth_token` in config/releases.exs
      api_key: "secret"

Now publish the package:

$ mix hex.publish package

Finally, let's use this package from another project.

First, configure Hex to use the custom repository:

$ cd /path/to/mini_repo
$ mix hex.repo add test_repo http://localhost:4000/repos/test_repo --public-key priv/test_repo_public.pem

Now, create a new Mix project:

$ mix new bar
$ cd bar

And configure the dependency, note the repo configuration option.

  defp deps() do
      {:foo, "~> 0.1", repo: "test_repo"}

Since the development server includes a hexpm_mirror repo, let's try that too:

$ HEX_MIRROR_URL=http://localhost:4000/repos/hexpm_mirror mix hex.package fetch decimal 1.8.0

See guide on publishing packages and Hex docs, in particular mix help hex.config, for more information.

Usage with Rebar3

Let's create a new package and publish it to our test_repo repository:

$ rebar3 new lib baz
$ cd baz

Now, let's configure Rebar3 to use our custom repo, put the following into your global rebar3 configuration:

%% ~/.config/rebar3/rebar.config
{plugins, [rebar3_hex]}.
{hex, [
  {repos, [
      name => <<"test_repo">>,

      %% make sure to change it, see `auth_token` in config/releases.exs
      api_key => <<"secret">>,
      api_url => <<"http://localhost:4000/api/repos/test_repo">>,
      api_repository => undefined,

      repo_url => <<"http://localhost:4000/repos/test_repo">>,
      repo_organization => undefined,
      repo_public_key => <<"-----BEGIN RSA PUBLIC KEY-----
-----END RSA PUBLIC KEY-----">>

And publish the package specifying the repo:

$ rebar3 hex publish -r test_repo

Finally, let's use this package from another project:

$ rebar3 new lib qux
$ cd qux

Add the dependency to the project's rebar.config:

{erl_opts, [debug_info]}.
{deps, [
  {baz, "0.1.0"}

And make sure the dependecy was correctly resolved:

$ rebar3 deps
===> Verifying dependencies...
baz (package 0.1.0)

See guide on publishing packages with Rebar3 and Rebar3 docs for more information.

Deployment with releases

It's recommended to deploy MiniRepo with Elixir releases.

Let's now assemble the release locally:

$ MIX_ENV=prod mix release
* assembling mini_repo-0.1.0 on MIX_ENV=prod

And start it:

PORT=4000 \
MINI_REPO_URL=http://localhost:4000 \
_build/prod/rel/mini_repo/bin/mini_repo start

As you can see, some configuration can be set by adjusting system environment variables, see config/releases.exs

Warning: MiniRepo by default has very basic authorization uses pre-generated public/private keys for repository signing. Make sure to generate your own public/private keys and consider adding authentication that makes sense in your organization.

Also, see mix help release for general information on Elixir releases.

More information

See following modules documentation to learn more about given feature:


The goal of MiniRepo is to provide a minimal server that implements Hex specifications. Why minimal? By keeping the project focused on bare minimum we hope it's easy to understand and serves as a good starting point for a more complete solution that makes sense in a given organization. A production grade system should include infrastructure for monitoring, backups, SSL, and more, not to mention features like user management, SSO and such, but that's out of the scope of MiniRepo project.

We welcome anyone to contribute to the project, especially around documentation and guides, but features specific to narrow set of users likely won't be accepted. For a complete and production-grade implementation see source code of, however keep in mind it's optimised for running the public registry for the community and thus have different features and constraints than a self-hosted solution might have.


Copyright (c) 2019 Plataformatec Copyright (c) 2020 Dashbit

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.


MiniRepo allows self-hosting of Hex packages.



No packages published