Setting Apex Domain Content

Configure your AR.IO Gateway to serve custom content from the apex domain instead of the default Arweave network information. This allows you to customize your gateway's root domain with useful information, project details, or any content you wish to share.

Overview

Prior to gateway Release 28, the apex domain of a gateway would only display information about the Arweave network. Release 28 introduced two new environment variables that allow a gateway to serve custom content from the apex domain:

APEX_TX_ID: Set to serve content from a specific transaction ID
APEX_ARNS_NAME: Set to serve content from an ArNS name

These variables enable gateway operators to customize their gateway's apex domain with useful information, details about the operator or associated projects, or any other content they wish to share.

Quick Start

Choose Your Content Source

Decide how you want to serve your content:

Option 1: Direct Transaction ID

Upload your content to Arweave
Use the transaction ID directly

Option 2: ArNS Name (Recommended)

Upload your content to Arweave
Assign your content's transaction ID to an ArNS name
Use the ArNS name for easier management

Upload Your Content

Upload your dApp, website, or other content to Arweave using your preferred method:

ArDrive - For simple file uploads
Turbo - For application bundles
Direct upload - For advanced users

Configure Environment Variable

Add one of these variables to your .env file:

# Option 1: Direct transaction ID
APEX_TX_ID=your-transaction-id

# Option 2: ArNS name (recommended)
APEX_ARNS_NAME=your-arns-name

IMPORTANT

You cannot set both variables simultaneously. Providing both variables will result in an error.

Restart Your Gateway

Restart your gateway to apply the changes:

docker compose down
docker compose up -d

Verify Configuration

Visit your gateway's apex domain to confirm the custom content is being served correctly.

Configuration Methods

Using Direct Transaction ID

Upload Content

Upload your content to Arweave and note the transaction ID:

# Example: Upload using ArDrive CLI
ardrive upload-file --file-path ./my-website.html

# Note the returned transaction ID
# Example: abc123...def789

Set Environment Variable

Add the transaction ID to your .env file:

APEX_TX_ID=abc123...def789

Restart Gateway

Restart your gateway to apply the configuration:

docker compose down
docker compose up -d

Update Content

To update your content:

Upload new content to Arweave
Update APEX_TX_ID with the new transaction ID
Restart your gateway

Advantages:

Direct control over content
No additional ArNS setup required
Simple for one-time content

Disadvantages:

Requires gateway restart for updates
Less flexible for content management

Using ArNS Name (Recommended)

Upload Content

Upload your content to Arweave:

# Upload your website or dApp
ardrive upload-file --file-path ./my-dapp.html
# Note the transaction ID: xyz789...abc123

Register ArNS Name

Visit ArNS App
Connect your wallet
Choose your desired name (e.g., my-gateway-content)
Set the transaction ID: xyz789...abc123
Pay the registration fee

Configure Environment Variable

Add the ArNS name to your .env file:

APEX_ARNS_NAME=my-gateway-content

Restart Gateway

Restart your gateway to apply the configuration:

docker compose down
docker compose up -d

Update Content

To update your content:

Upload new content to Arweave
Update the ArNS name to point to the new transaction ID
No gateway restart required!

Advantages:

No restart required for content updates
Easy content management
Professional domain naming
Can be updated independently

Disadvantages:

Requires ArNS setup
Additional cost for ArNS registration

Advanced Setup Options

Custom Content Types

Configure different types of content:

Static Website:

# Upload HTML/CSS/JS files
APEX_ARNS_NAME=my-gateway-website

Single Page Application:

# Upload SPA bundle
APEX_ARNS_NAME=my-dapp

Documentation Site:

# Upload documentation
APEX_ARNS_NAME=my-gateway-docs

Content Management Workflow

Implement a content management workflow:

Development - Test content locally
Upload - Deploy to Arweave
Register - Create/update ArNS name
Verify - Check content on gateway
Monitor - Track performance and usage

Use Cases and Examples

Display Gateway Service Information

Perfect for showcasing your gateway service:

Content Ideas:

Gateway operator information
Service capabilities and features
Contact information
Status and uptime statistics
Network participation details

Example Structure:

<!DOCTYPE html>
<html>
  <head>
    <title>My AR.IO Gateway</title>
    <meta charset="utf-8" />
  </head>
  <body>
    <h1>AR.IO Gateway Service</h1>
    <p>Reliable gateway infrastructure for the permanent web</p>
    <ul>
      <li>High availability</li>
      <li>Fast response times</li>
      <li>Global CDN</li>
    </ul>
    <p>Contact: operator@example.com</p>
  </body>
</html>

Showcase Associated Projects

Highlight your projects and services:

Content Ideas:

Project portfolio
Service offerings
Recent updates and news
Links to other projects
Integration examples

Example Structure:

<!DOCTYPE html>
<html>
  <head>
    <title>My Projects - AR.IO Gateway</title>
  </head>
  <body>
    <h1>My Projects</h1>
    <div class="project">
      <h2>Project Alpha</h2>
      <p>Description of project and its features</p>
      <a href="https://project-alpha.example.com">Visit Project</a>
    </div>
    <div class="project">
      <h2>Project Beta</h2>
      <p>Another project description</p>
      <a href="https://project-beta.example.com">Visit Project</a>
    </div>
  </body>
</html>

Host Documentation

Provide comprehensive documentation:

Content Ideas:

Gateway setup guides
API documentation
Integration tutorials
Troubleshooting guides
FAQ sections

Example Structure:

<!DOCTYPE html>
<html>
  <head>
    <title>Gateway Documentation</title>
    <style>
      .nav {
        float: left;
        width: 200px;
      }
      .content {
        margin-left: 220px;
      }
    </style>
  </head>
  <body>
    <div class="nav">
      <h3>Navigation</h3>
      <ul>
        <li><a href="#setup">Setup Guide</a></li>
        <li><a href="#api">API Reference</a></li>
        <li><a href="#troubleshooting">Troubleshooting</a></li>
      </ul>
    </div>
    <div class="content">
      <h1>Gateway Documentation</h1>
      <section id="setup">
        <h2>Setup Guide</h2>
        <p>Step-by-step setup instructions...</p>
      </section>
    </div>
  </body>
</html>

Real-World Examples

Several gateway operators have implemented this feature:

arweave.tech

Serves a custom landing page with gateway service information
Professional presentation of capabilities

arlink.xyz

Serves the permaDapp for the Arlink project
Demonstrates integration with existing projects

frostor.xyz / love4src.com

Serves information about the Memetic Block Software Guild
Showcases community and project information

vilenarios.com

Serves personalized portfolio/link tree information
Personal branding and contact information

permagate.io

Serves personalized link tree information
Professional operator presence

These examples demonstrate the flexibility of the apex domain feature and how different operators use it to create unique, personalized experiences for their users.

# Check if variables are set correctly
grep -E "APEX_(TX_ID|ARNS_NAME)" .env

# Should show only one of:
# APEX_TX_ID=your-transaction-id
# APEX_ARNS_NAME=your-arns-name

Ensure you have only ONE of the APEX variables set, not both.

Verify Gateway Restart

Ensure your gateway has been restarted after configuration changes:

# Check if gateway is running
docker compose ps

# Restart if needed
docker compose down
docker compose up -d

Check Gateway Logs

Review logs for any error messages:

docker compose logs ar-io-core | grep -i apex

Resolve Content Issues

Verify Content Accessibility

Test if your content is accessible:

# Test transaction ID directly
curl -I https://arweave.net/your-transaction-id

# Test ArNS name resolution
curl -I https://your-arns-name.arweave.net

Check Content Format

Ensure your content is properly formatted:

HTML content should have proper DOCTYPE
Text content should be UTF-8 encoded
Binary content should have appropriate Content-Type headers

Test Content Rendering

Verify content renders correctly in different browsers:

Test in Chrome, Firefox, Safari
Check mobile responsiveness
Verify all links work correctly
Test with different screen sizes

Fix ArNS Problems

Verify ArNS Resolution

Check if your ArNS name resolves correctly:

# Test ArNS resolution
nslookup your-arns-name.arweave.net

# Check if it points to the correct transaction
curl -s https://your-arns-name.arweave.net | head -10

Update ArNS Record

If ArNS name points to wrong content:

Go to ArNS App
Find your ArNS name
Update the transaction ID
Wait for propagation (usually immediate)

Check ArNS Status

Verify ArNS name is active and not expired:

Visit the ArNS app
Check your name's status
Ensure it's not expired
Verify payment is up to date

Keep file sizes reasonable
Use efficient HTML/CSS
Optimize images and assets
Minimize external dependencies

Ensure Accessibility

Use semantic HTML
Include alt text for images
Ensure good color contrast
Test with screen readers

Mobile Responsiveness

Design for mobile-first
Use responsive CSS
Test on various devices
Ensure touch-friendly interfaces

Content Management

Version Control

Keep content in version control
Document changes and updates
Test changes before deployment
Maintain backup copies

Regular Updates

Keep information current
Update contact details
Refresh project information
Monitor for broken links

Backup Strategy

Backup content regularly
Keep multiple copies
Document restoration procedures
Test backup recovery

Next Steps

Ready to customize your gateway? Start with the Quick Start section above, then explore the different configuration methods and use cases to find what works best for your needs.

Additional Resources

ArNS Documentation - Learn more about ArNS names and management
Content Upload Guides - Best practices for uploading content to Arweave
Gateway Configuration - Advanced gateway configuration options
Community Examples - See how other operators use this feature

Getting Help

If you encounter issues:

Check the troubleshooting section above
Verify your configuration is correct
Test content accessibility independently
Consult the AR.IO Discord for community support

How is this guide?

Setting Apex Domain Content

On this page