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.
Requirements
Section titled “Requirements”- 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:16image. - Yarn 4, through
corepack. - About 2 GB of memory at the least, for image processing with
sharp.
Quick start
Section titled “Quick start”# Clonegit clone https://github.com/gibsfinance/assets.gitcd assets
# Installcorepack enableyarn install
# Start a local database (Docker)yarn db:up
# Start the server (it applies database migrations when it starts)yarn server:devSet 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:
yarn collectFor 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.
Architecture
Section titled “Architecture”┌─────────────────────────────────────────────┐│ 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.
Pages in this section
Section titled “Pages in this section”| 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 |