We can customize Wormholes with environment variables. The default values are there to make them work on local setup, for production these needs modifications.

Distributed Mode

Customizing ports

Wormholes comprises three services: Director, Generator, and Creator. In distributed mode, each service runs on a specific port. You can customize these ports using PORT environment variable.

Default Ports

  • Director - 5000
  • Generator - 5001
  • Creator - 5002

Customizing database connections

Wormholes uses TimescaleDB, PostgreSQL and Redis. You can customize connection to these databses using environment variables as follows —


  • TS_URI- This controls the URI for connecting to TimescaleDB. The default is postgres://postgres:postgres@localhost:5433/postgres.


  • PG_URI - This controls the URI for connecting to PostgreSQL. The default is postgres://postgres:postgres@localhost:5432/postgres.
  • PG_MAX_CONN - This controls the max connections for PostgreSQL. The default is 5000.


  • REDIS_URI - THis controls the URI connecting to Redis and the default is redis://:redis@localhost:6379/0.

Links generated in Creator are ingested in a batch to avoid excessive database connections. We can control it's behaviour with following environment variables —

  • BATCH_SIZE - This controls number of links ingested in a batch. The default value is 10000.

Events ingestion

When a link in clicked, an event is generated in Director. All such events are ingested to a time-series database ( TimescaleDB by default ). We can control it with following envrionment variables —

  • BATCH_SIZE - This controls number of events ingested in a batch. The default value is 10000.
  • STREAMS - I this controls the number of streams that process events. The default value is 8.

Customizing Generator

  • ID_SIZE - This controls the size of generated IDs. The default value is 7.
  • BLOOM_MAX - This configures bloomfilters based on approx number of IDs to store. The default value is 1000000.
  • BLOOM_ERROR - This controls the rate of false positives in bloom filter and the default is 0.0000001.
  • BUCKET_SIZE - Inside generator, IDs to be used are stored in buckets. This controls the number of buckets to store IDs 8.
  • BUCKET_CAP - This controls the number of IDs to store in a single bucket which is 100000 by default.

Connecting Creator to Generator

The Creator connects with Generator over grpc and the url to generator instance can be controlled with GEN_ADDR. The default is localhost:5001.

Unified mode

Unified mode uses same environment variables as distributed one with following changes.

  • The PORT defaults to 5000
  • The GEN_ADDR is not required as everything runs in a single service.