API server and website for https://hex.pm.
To contribute to Hexpm you need to properly set up your development environment.
Also see the client repository: hex. The client uses hexpm for integration tests, so hexpm needs to support all versions the client supports. CI ensures that tests are run on all supported versions.
- Run
mix setupto install dependencies, create and seed database etc - Run
mix test - Run
iex -S mix phx.serverand visit http://localhost:4000/
After this succeeds you should be good to go!
See setup alias in mix.exs and sections below for more information or when you run into issues.
PostgreSQL version should be >= 9.4, as Hexpm uses the jsonb type, that is available from PostgreSQL 9.4 onward.
Hexpm requires the PostgreSQL modules pg_trgm and pgcrypto to be available.
This is located in the "postgresql-contrib" package, however the package name can vary depending on your operating system. If the module is not installed the ecto migrations will fail.
By default, Hexpm connects to a localhost PostgreSQL database hexpm_dev using the username postgres with the password postgres.
Development object storage is shared across worktrees under the operating system's temporary directory. Set HEXPM_LOCAL_STORE_DIR to use a different shared location.
Create the database and user 'postgres' if not already done:
docker-compose up -d dbNow you are fine to create the hexpm_dev database and run the ecto migrations:
mix do ecto.create + ecto.migrateUsing the following command you can seed your local Hexpm instance with some sample data:
mix run priv/repo/seeds.exsIt's recommended to enable Corepack for a better developer experience:
corepack enableFor assets compilation we need to install Node dependencies:
cd assets && yarn installIf you don't have yarn installed, cd assets && npm install will work too.
Once the database is set up you can start Hexpm:
# with console
iex -S mix phx.server
# without console
mix phx.serverHexpm will be available at http://localhost:4000/.
The dashboard audit log (/dashboard/audit-logs) shows the country of each
entry's IP, resolved at render time via the :geo_impl implementation:
- dev / test use
Hexpm.Geo.Local— no database required. It resolves IPs from the:geo_local_lookupsmap inconfig/dev.exs(localhost is mapped by default); add entries there to exercise other countries. - production uses
Hexpm.Geo.Geolix, which reads an MMDB IP-to-country database viageolix.
The production database is the free DB-IP IP-to-Country Lite file (CC BY 4.0 — attribution is rendered on the page; any MaxMind-compatible MMDB also works).
Docker (default): nothing to do. The image fetches the database at build time and bakes it into the release, and the app finds it automatically — geolocation works out of the box. Each image build re-fetches the current file (DB-IP refreshes monthly), so routine rebuilds keep it reasonably fresh.
Other deployments / custom location: download it and point Hexpm at the file:
mix download_geoip # -> priv/geoip/country.mmdb
export HEXPM_GEOIP_COUNTRY_PATH=priv/geoip/country.mmdbRe-run the task and restart (or call Geolix.reload_databases/0) to update.
Fail-soft: if no database is found the app boots normally and audit log locations are simply omitted until one is provisioned.
HEXPM_GEOIP_COUNTRY_PATHoverrides the baked-in default.
Integration tests exercise the full chain: hexpm -> hexpm_billing -> Stripe. They are excluded from regular mix test runs and require additional setup.
-
Create a Stripe sandbox (if you don't already have one):
Go to the Stripe Dashboard, open the account picker, click "Switch to sandbox", then "Create sandbox". Give it a name (e.g. "hexpm-dev").
-
Install and authenticate the Stripe CLI:
brew install stripe/stripe-cli/stripe stripe login
This opens a browser where you select which sandbox to log into. The CLI generates restricted keys valid for 90 days, stored in
~/.config/stripe/config.toml. -
Configure hexpm_billing with your sandbox keys:
Copy the API keys from your sandbox's API keys page and update
hexpm_billing/config/dev.exs:stripe_secret_key— your sandbox secret key (sk_test_...)stripe_publishable_key— your sandbox publishable key (pk_test_...)
-
Forward Stripe webhooks to hexpm_billing:
stripe listen --forward-to localhost:4001/webhooks/payments
The CLI will print a webhook signing secret (
whsec_...). Updatestripe_signing_secret_keyinhexpm_billing/config/dev.exswith this value. The secret stays the same between CLI restarts.
-
hexpm_billing running locally on port 4001:
# In the hexpm_billing repo mix deps.get mix ecto.setup MIX_ENV=dev mix phx.server -
ChromeDriver installed (for browser tests):
brew install chromedriver
-
Stripe CLI forwarding webhooks (see above):
stripe listen --forward-to localhost:4001/webhooks/payments
# All integration tests
mix test --only integration
# Only browser/SCA tests
mix test test/hexpm_web/integration/sca_test.exs --include integrationStaged publishing follows the Workload Identity rollout flag:
HEXPM_WORKLOAD_IDENTITY_MODE, with HEXPM_WORKLOAD_IDENTITY_BETA_USERS and
HEXPM_WORKLOAD_IDENTITY_BETA_ORGANIZATIONS in beta. Public packages follow their
owners in beta; private packages follow their organization.
Staged package and documentation tarballs use the existing repo bucket under
staged/, with private, non-cacheable responses. The CDN origin identity must be
denied access to this prefix, and backups must exclude it. Staged releases can be
approved for seven days; approval, rejection, restaging and expiry enqueue artifact
cleanup.
S3 lifecycle rules expire remaining current objects after 14 days and noncurrent
versions after one day. Lifecycle deletion is asynchronous. Deploy the
hexpm-ops storage rules and backup exclusion before staged publishing reaches an
environment where the Workload Identity flag is on.
Development and test use the existing local and memory repo stores.
Each package has an optional approval setting covering all API keys and workload identities that publish it, on by default for new packages. Existing packages keep direct publishing until approval is enabled. Full owners configure it under Settings > Staged publishing; changes require two-factor authentication and fresh sudo, and disabling sends a notification to full owners and owning organization administrators. These settings take effect where the Workload Identity flag is on. Both public and private publishing follow the package's setting. An organization administrator can require approval for API keys and workload identities in its private repository under Staged publishing in the dashboard. User OAuth publishes with an OTP remain direct.
Staged publishing doesn't change how API keys and workload identities are created
or managed. A key is only created by a signed-in person: on the dashboard behind
sudo, which asks for the 2FA code when the account has 2FA, or through the API with
an OAuth token and a valid X-Hex-OTP. API keys can't create keys.
Staged publishing doesn't change who can add owners or organization members. An API
key with api:write, owners, package:name or members can add an owner or
member, who can then publish from their own account with OAuth and an OTP without
being staged. The publishing guide and the keys docs recommend Workload Identity
over API keys for CI, and keys limited to the permissions the job needs.
Review and approval are available under Staged releases. Approval and rejection require 2FA and forced sudo; approval also binds to the displayed package and documentation checksums. Staged releases expire after seven days, and a periodic worker removes them and queues artifact deletion.
Registry operators can set HEXPM_FORCE_STAGED_PUBLISHING=true to require human
approval with fresh 2FA for every API-key, organization-key OAuth exchange, and
workload-identity publish of a public package, including documentation. This
applies regardless of package settings or Workload Identity rollout lists. None of
these credentials can revert public releases or documentation. Private
repositories keep their package and organization settings. Human OAuth publishing
with an OTP remains direct.
The website displays a banner while this mode is active. The override uses the
same repo-bucket staged/ prefix and retention rules and doesn't remove existing
owners or memberships.
Copyright 2015 Six Colors AB
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
http://www.apache.org/licenses/LICENSE-2.0
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.