PubNet

Self-hosted pub.dev alternative.

Contents

• Development
  • Architecture
  • Debugging
• Contributions
• Hosting
  • Using docker-compose.yml
  • Other approaches
• License
• Screenshots

---

Development

The src folder of this repository contains a docker-compose.yml, which contains three services used to aid in developing PubNet:

• database: A postgres database (user: pubnet, password: pubnet)
• adminer: A webinterface for managing the database
• seq: A useful logging service

The only service you need to start is database, though the other services help a lot.

Note

You can also use a database you set up on your host, but currently only postgres is supported.

Architecture

The solution consists of a few projects, three of them compose the whole PubNet service:

• PubNet.API: provides the API used by the dart pub command line tool to fetch and upload new packages
• PubNet.Frontend: contains a Blazor WebAssembly project to act as a frontend for the API
• PubNet.Worker: executes tasks (scheduled and unscheduled) to analyze packages and do general housekeeping

Debugging

You can use any IDE you want, as long as it supports debugging .NET 10 or higher.

For the PubNet.Frontend project, it is recommended to run it using dotnet watch to hot-reload changes.

Database migrations

This project uses Entity Framework Core with the code-first approach, so migrations are added using dotnet ef migrations add <name> and executed using dotnet ef database update in the PubNet.Database project folder. Currently, the database project expects the credentials and database name to all be equal to pubnet.

Contributions

If you want to contribute improvements or bugfixes, fork this repository, create a branch, commit your changes to it and open a pull request here on GitHub.

Hosting

Note

In case you only need a simple, privately hosted pub package API, the API project alone is sufficient.

When you are ready to deploy PubNet, you may want to review the OpenRegistration setting in the backend-appsettings.json to toggle whether anyone is able to register an account. This setting can be changed at runtime.

Hosted upstream

PubNet can fall back to an upstream hosted repository for package metadata and archives that are not stored locally.

• The default upstream is https://pub.dev/api/.
• You can point it at unpub by setting HostedUpstream:BaseUrl to the upstream API base URL, for example https://unpub.example.com/api/.
• Environment variables override JSON configuration in ASP.NET Core, so Docker deployments can use HostedUpstream__BaseUrl.
• If the configured value is missing or invalid, PubNet falls back to https://pub.dev/api/.

Example values:

{
  "HostedUpstream": {
    "BaseUrl": "https://unpub.example.com/api/"
  }
}

export HostedUpstream__BaseUrl="https://unpub.example.com/api/"

Important behavior notes:

• The upstream URL must be the API base URL, not just the site root.
• PubNet still stores and manages its own local packages, authors, and permissions.
• Only package lookups and archive fallback use the upstream. Package list pages and author data remain local to PubNet.

Using docker-compose.yml

docker-compose.yml template

Create a docker-compose.yml with the following contents:

volumes:
  postgres_data:
  pubnet_packages:
  caddy_data:
  caddy_config:

services:
  database:
    image: postgres:18
    restart: always
    environment:
      POSTGRES_USER: "pubnet"
      POSTGRES_PASSWORD: "pubnet"
    volumes:
      - postgres_data:/var/lib/postgresql

  backend:
    image: ghcr.io/ricardoboss/pubnet/api:main
    restart: always
    environment:
      HostedUpstream__BaseUrl: "https://unpub.example.com/api/"
    volumes:
      - "./backend-appsettings.json:/app/appsettings.Production.json"
      - "pubnet_packages:/app/packages"
    depends_on:
      - database
      - caddy

  worker:
    image: ghcr.io/ricardoboss/pubnet/worker:main
    restart: always
    volumes:
      - "./worker-appsettings.json:/app/appsettings.Production.json"
      - "pubnet_packages:/app/packages"
    depends_on:
      - database

  frontend:
    image: ghcr.io/ricardoboss/pubnet/frontend:main
    restart: always
    depends_on:
      - backend
      - caddy

  # you can choose any reverse proxy you want, Caddy is not required
  caddy:
    image: caddy
    restart: always
    volumes:
      - "./Caddyfile:/etc/caddy/Caddyfile"
      - "caddy_data:/data"
      - "caddy_config:/config"
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"

Note

In this example, caddy is used as a reverse-proxy.

You can also host the backend and frontend on different ports, and publish them directly, removing the need to configure a reverse proxy entirely.

Reverse proxy configuration (Caddyfile)

In case you want a reverse proxy, configure it appropriately (in this case using a Caddyfile):

*:80, *:443 {
    reverse_proxy /api/* backend:80
    reverse_proxy /* frontend:80
}

backend-appsettings.json template

{
  "AllowedOrigins": [
    "http://localhost"
  ],
  "ConnectionStrings": {
    "PubNet": "Host=database;Database=pubnet;Username=pubnet;Password=pubnet"
  },
  "Jwt": {
    "Issuer": "http://localhost",
    "Audience": "http://localhost",
    "SecretKey": "GenerateASecureKey!"
  },
  "PackageStorage": {
    "Path": "./packages"
  },
  "HostedUpstream": {
    "BaseUrl": "https://pub.dev/api/"
  },
  "OpenRegistration": true,
  "SmtpAccount": {
    "Host": "localhost",
    "Port": 1025,
    "TLS": false,
    "Login": "myMtaLogin",
    "Password": "myMtaPassword"
  }
}

worker-appsettings.json template

Add a worker-appsettings.json:

You could use the same appsettings for the worker and the backend as their options shouldn't interfere.

{
  "ConnectionStrings": {
    "PubNet": "Host=database;Database=pubnet;Username=pubnet;Password=pubnet"
  },
  "PackageStorage": {
    "Path": "./packages",
    "PendingMaxAge": "00:05:00"
  }
}

Docker environment variable override

If you do not want to store the upstream in backend-appsettings.json, set it directly in the backend container environment:

services:
  backend:
    image: ghcr.io/ricardoboss/pubnet/api:main
    environment:
      HostedUpstream__BaseUrl: "https://unpub.example.com/api/"

When HostedUpstream__BaseUrl is empty, missing, or not a valid absolute http/https URL, PubNet falls back to https://pub.dev/api/.

Finally, start your own PubNet using

docker-compose up -d

and access it at https://localhost.

Other approaches

It should be possible to host the API using IIS, but it is not supported.

Same goes for the Worker: it should be possible to run it as a Windows service/systemd unit, but is not supported.

The frontend can be hosted from anywhere, as long as the backend-appsettings.json contains the domain to allow CORS.

License

This project is licensed under the Apache 2.0 license. For more information, see LICENSE.

Screenshots

This is a screenshot of how a package looks like after uploading and analysis:

This screenshot shows different versions in a table: