Self-Hosting

Deploy and manage your own Grat relay instance.

Grat is designed to be self-hostable, giving you full control over your sponsorship infrastructure, channel accounts, and security policies.

Prerequisites

• Node.js 20+: The relay is built with TypeScript and Node.js.
• Docker & Docker Compose: Recommended for production deployments.
• Redis: Used for channel locking and sequence number management.
• PostgreSQL: Used for persistent storage of API keys and logs.
• Stellar Account: At least one funded Stellar account to act as a fee channel.

Deployment with Docker

The fastest way to deploy Grat is using the provided Docker Compose configuration.

1. Clone and Configure

   Clone the repository and create your environment file.

   git clone https://github.com/gratnetwork/grat.git
   cd grat
   cp .env.example .env
   
2. Update Environment Variables

   Edit the .env file to include your database credentials, Redis URL, and Stellar configurations. See the variables table below for details.

3. Start the Services

   Launch the relay and its dependencies.

   docker-compose up -d
   
4. Create Channels

   Generate and fund your internal channel accounts.

   npm run create-channels
   
5. Verify Health

   Check that the relay is running correctly.

   curl http://localhost:3000/health
   

Environment Variables

Variable	Description	Default
PORT	The port the relay server listens on.	3000
NETWORK	testnet or mainnet.	testnet
RPC_URL	The URL of your Stellar RPC provider.	Required
DATABASE_URL	PostgreSQL connection string.	postgresql://...
REDIS_URL	Redis connection string.	redis://...
CHANNEL_COUNT	Number of parallel fee channels to maintain.	10
CHANNEL_SEED_PHRASE	Mnemonic for deriving channel accounts.	Required
ADMIN_TOKEN	Token for administrative API access.	Required
DEPOSIT_ADDRESS	Stellar address to receive credit deposits.	Optional
DEPOSIT_POLL_INTERVAL_MS	Frequency to poll for new deposits.	5000
FEE_MULTIPLIER	Multiplier for base fees on classic transactions.	1.5

Stellar requires an RPC provider for mainnet access. The SDF does not host a free mainnet RPC endpoint. We recommend using a professional provider such as Quicknode, Blockdaemon, or Validation Cloud. For testnet, you can use the SDF’s free testnet RPC at https://soroban-testnet.stellar.org.

Channel Account Management

Channels are the backbone of the relay. They provide the sequence numbers and XLM needed to pay for sponsored transactions.

• Creation: Grat derives channel accounts from a single seed phrase using BIP39.
• Funding: In production, you must fund these accounts with enough XLM to cover your expected transaction volume.
• Monitoring: The /health endpoint provides data on individual channel balances and availability.

Cloud Platforms

Railway

1. Connect your GitHub repo.
2. Add PostgreSQL and Redis plugins.
3. Configure environment variables in the Railway dashboard.
4. Deploy.

Render

1. Create a “Web Service” from your repo.
2. Create managed PostgreSQL and Redis instances.
3. Link environment variables.
4. Set the build command to npm run build and start command to npm start.

Fly.io

1. Run fly launch to initialize the project.
2. Provisions DB and Redis via Fly’s extensions.
3. Set secrets using fly secrets set.
4. Deploy using the included Dockerfile.

Monitoring and Metrics

Grat exposes a /metrics endpoint compatible with Prometheus. You can monitor:

• Request counts and latency.
• Active vs locked channel accounts.
• Success vs failure rates for sponsored submissions.
• Total XLM spent across all channels.

Never share your CHANNEL_SEED_PHRASE or ADMIN_TOKEN. These provide full control over your fee accounts and relay configuration.

Managed cloud hosting is coming soon for teams who prefer zero infrastructure overhead. Join our newsletter to be notified when we launch.

View on GitHub