Skip to content

Self-hosting overview

You can run your own Gib instance, for private use or for public use. It serves token metadata and images the same way the public instance at gib.show does. The server, the collector and the interface all live in the public repository at github.com/gibsfinance/assets.

  • Node.js 22 or later. Node.js 24 is recommended, because it matches the Docker image and the continuous integration runs.
  • PostgreSQL 14 or later. The repository’s Docker Compose file uses the plain postgres:16 image.
  • Yarn 4, through corepack.
  • About 2 GB of memory at the least, for image processing with sharp.
Terminal window
# Clone
git clone https://github.com/gibsfinance/assets.git
cd assets
# Install
corepack enable
yarn install
# Start a local database (Docker)
yarn db:up
# Start the server (it applies database migrations when it starts)
yarn server:dev

Set DATABASE_URL in your shell to point at your database. See Configuration for every setting. Without it, the server uses a local default database on port 5876.

The database is empty at first. Run the collector to fill it:

Terminal window
yarn collect

For a full first-time setup in one command, run yarn workspace server run setup. It builds the images, starts the database, runs the migrations, seeds the database, runs a first collection and creates the provider orders.

┌─────────────────────────────────────────────┐
│ Content delivery network │
│ (optional, for edge caching) │
└──────────────────┬──────────────────────────┘
│
┌──────────────────▼──────────────────────────┐
│ Express Server │
│ ┌─────────┐ ┌──────────┐ ┌────────────┐ │
│ │ /image │ │ /list │ │ /networks │ │
│ │ routes │ │ routes │ │ routes │ │
│ └────┬────┘ └──────────┘ └────────────┘ │
│ │ │
│ ┌────▼────┐ ┌──────────┐ │
│ │ sharp │ │ Resize │ │
│ │ resize │──│ variant │ │
│ └─────────┘ │ cache │ │
│ └──────────┘ │
└──────────────────┬──────────────────────────┘
│
┌──────────────────▼──────────────────────────┐
│ PostgreSQL │
│ ┌─────────┐ ┌──────────┐ ┌────────────┐ │
│ │ image │ │ token │ │ list │ │
│ │ (rows) │ │ │ │ │ │
│ ├─────────┤ ├──────────┤ ├────────────┤ │
│ │ image_ │ │ list_ │ │ provider │ │
│ │ variant │ │ token │ │ │ │
│ └─────────┘ └──────────┘ └────────────┘ │
└─────────────────────────────────────────────┘

Image bytes live in a content-addressed store, which you choose with IMAGE_STORE. See Image storage.

Page What it covers
Configuration Every environment variable
Running the server Start commands, Docker, migrations, monitoring, scaling
Domains and reverse proxies Host names, DNS records, public address settings, Caddy, nginx, content delivery networks
Collection How data gets in, provider priority, the artwork repositories
Etherscan collector Settings and the check command
Image storage Choosing a store and every store setting
Moving between stores Copy, export, verify, import and garbage collection
Image resizing On-the-fly resizing and its limits