Skip to content
pesde / docs

Self Hosting Registries

You can self host registries for pesde. This is useful if you want a private registry or if you a separate registry for other reasons.

Making the index repository

The index is a repository that contains metadata about all the packages in the registry.

An index contains a config.toml file with configuration options.

To create an index, create a new repository and add a config.toml file with the following content:

config.toml
# the URL of the registry API
api = "https://registry.acme.local/"


# package download URL (optional)
download = "{API_URL}/v1/packages/{PACKAGE}/{PACKAGE_VERSION}/{PACKAGE_TARGET}/archive"


# the client ID of the GitHub OAuth app (optional)
github_oauth_client_id = "a1d648966fdfbdcd9295"


# whether to allow packages with Git dependencies (default: false)
git_allowed = true


# whether to allow packages which depend on packages from other registries
# (default: false)
other_registries_allowed = ["https://git.acme.local/index"]


# whether to allow packages with Wally dependencies (default: false)
wally_allowed = false


# the maximum size of the archive in bytes (default: 4MB)
max_archive_size = 4194304


# the scripts packages present in the `init` command selection by default
scripts_packages = ["pesde/scripts_rojo"]

  • api: The URL of the registry API. See below for more information.

  • download: The URL to download packages from. This is optional and defaults to the correct URL for the official pesde registry implementation. You only need this if you are using a custom registry implementation.

    This string can contain the following placeholders:

    • {API_URL}: The API URL (as specified in the api field).
    • {PACKAGE}: The package name.
    • {PACKAGE_VERSION}: The package version.
    • {PACKAGE_TARGET}: The package target.

    Defaults to {API_URL}/v1/packages/{PACKAGE}/{PACKAGE_VERSION}/{PACKAGE_TARGET}/archive.

  • github_oauth_client_id: This is required if you use GitHub OAuth for authentication. See below for more information.

  • git_allowed: Whether to allow packages with Git dependencies. This can be either a bool or a list of allowed repository URLs. This is optional and defaults to false.

  • other_registries_allowed: Whether to allow packages which depend on packages from other registries. This can be either a bool or a list of allowed index repository URLs. This is optional and defaults to false.

  • wally_allowed: Whether to allow packages with Wally dependencies. This can be either a bool or a list of allowed index repository URLs. This is optional and defaults to false.

  • max_archive_size: The maximum size of the archive in bytes. This is optional and defaults to 4194304 (4MB).

  • scripts_packages: The scripts packages present in the init command selection by default. This is optional and defaults to none.

You should then push this repository to GitHub.

Configuring the registry

The registry is a web server that provides package downloads and the ability to publish packages.

The official registry implementation is available in the pesde GitHub repository.

Configuring the registry is done using environment variables. In order to allow the registry to access the index repository, you must use an account that has access to the index repository. We recommend using a separate account for this purpose.

General configuration

  • INDEX_REPO_URL: The URL of the index repository. This is required.
    Example: https://github.com/pesde-pkg/index.git

  • GIT_USERNAME: The username of a Git account that has push access to the index repository. This is required.

  • GIT_PASSWORD: The password of the account specified by GITHUB_USERNAME. This is required.

  • COMMITTER_GIT_NAME: The name to use for the committer when updating the index repository. This is required.
    Example: pesde index updater

  • COMMITTER_GIT_EMAIL: The email to use for the committer when updating the index repository. This is required.
    Example: pesde@localhost

  • DATA_DIR: The directory where the registry stores miscellaneous data. This value can use {CWD} to refer to the current working directory.
    Default: {CWD}/data

  • ADDRESS: The address to bind the server to.
    Default: 127.0.0.1

  • PORT: The port to bind the server to.
    Default: 8080

Authentication configuration

The registry supports multiple authentication methods, which are documented below.

General configuration

  • READ_NEEDS_AUTH: If set to any value, reading data requires authentication. If not set, anyone can read from the registry. This is optional.

Single token authentication

Allows read and write access to the registry using a single token.

  • ACCESS_TOKEN: The token to use for authentication.

Multiple token authentication

Allows read and write access to the registry using different tokens.

  • READ_ACCESS_TOKEN: The token that grants read access.
  • WRITE_ACCESS_TOKEN: The token that grants write access.

GitHub OAuth authentication

Allows clients to get read and write access to the registry using GitHub OAuth. This requires a GitHub OAuth app, instructions to create one can be found in the GitHub documentation.

  • GITHUB_CLIENT_SECRET: The client secret of the GitHub OAuth app.

No authentication

If none of the above variables are set, anyone will be able to read and write to the registry.

Storage configuration

The registry supports multiple storage backends, which are documented below.

File system storage

Stores packages on the file system.

  • FS_STORAGE_ROOT: The root directory where packages are stored.

S3 storage

Stores packages on an S3 compatible storage service, such as Amazon S3 or Cloudflare R2.

  • S3_ENDPOINT: The endpoint of the S3 bucket to store packages in.
  • S3_BUCKET_NAME: The name of the bucket.
  • S3_REGION: The region of the bucket.
  • S3_ACCESS_KEY: The access key to use.
  • S3_SECRET_KEY: The secret key to use.

Sentry configuration

The registry supports Sentry for error tracking.

  • SENTRY_DSN: The DSN of the Sentry instance.

Running the registry

First clone the repository and navigate to the repository directory:

Terminal window
git clone https://github.com/pesde-pkg/pesde.git
cd pesde

You can then build the registry using the following command:

Terminal window
cargo build --release -p pesde-registry

This will build the registry. The resulting binary will be located at target/release/pesde-registry or target/release/pesde-registry.exe.

After setting the environment variables, you can run the registry using the by executing the binary.

The registry must be exposed at the URL specified in the api field of the index repository configuration.