Simple Knot Self-Hosting Guide with Cloudflare Tunnel#

This guide will help you set up your own knot server using Cloudflare Tunnel, which handles SSL and eliminates the need for port forwarding.

Prerequisites#

• A Linux server (VPS, Raspberry Pi, etc.)
• A domain name managed by Cloudflare (free account works)
• Your Bluesky DID (find it at https://tangled.sh/settings)

Step 1: Install Dependencies#

# Update system
sudo apt update && sudo apt upgrade -y

# Install required packages
sudo apt install -y git golang-go build-essential

Step 2: Build and Install Knot#

# Clone the repository
git clone https://tangled.org/@tangled.org/core
cd core

# Build knot
export CGO_ENABLED=1
go build -o knot ./cmd/knot

# Move to system location
sudo mv knot /usr/local/bin/knot
sudo chown root:root /usr/local/bin/knot

Step 3: Create Git User and Configure SSH#

# Create git user
sudo adduser --disabled-password --gecos "" git

# Configure SSH for knot
sudo tee /etc/ssh/sshd_config.d/authorized_keys_command.conf <<EOF
Match User git
  AuthorizedKeysCommand /usr/local/bin/knot keys -o authorized-keys
  AuthorizedKeysCommandUser nobody
EOF

# Reload SSH
sudo systemctl reload sshd

Step 4: Configure Knot Environment#

# Create configuration file
sudo tee /home/git/.knot.env <<EOF
KNOT_REPO_SCAN_PATH=/home/git
KNOT_SERVER_HOSTNAME=knot.yourdomain.com
APPVIEW_ENDPOINT=https://tangled.sh
KNOT_SERVER_OWNER=did:plc:YOUR_DID_HERE
KNOT_SERVER_INTERNAL_LISTEN_ADDR=127.0.0.1:5444
KNOT_SERVER_LISTEN_ADDR=127.0.0.1:5555
EOF

# Set proper permissions
sudo chown git:git /home/git/.knot.env

Important: Replace knot.yourdomain.com with your actual subdomain and did:plc:YOUR_DID_HERE with your DID.

Step 5: Set Up Systemd Service#

# Download and install service file
sudo tee /etc/systemd/system/knotserver.service <<EOF
[Unit]
Description=Knot Server
After=network.target

[Service]
Type=simple
User=git
WorkingDirectory=/home/git
EnvironmentFile=/home/git/.knot.env
ExecStart=/usr/local/bin/knot server
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
EOF

# Enable and start the service
sudo systemctl daemon-reload
sudo systemctl enable knotserver
sudo systemctl start knotserver

# Check status
sudo systemctl status knotserver

Step 6: Install Cloudflare Tunnel#

# Download and install cloudflared
wget https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared-linux-amd64.deb

# Authenticate with Cloudflare
sudo cloudflared tunnel login

This will open a browser window. Log in to Cloudflare and select your domain.

Step 7: Create and Configure Tunnel via Cloudflare Dashboard#

1. Go to https://one.dash.cloudflare.com/
2. Select your account → Zero Trust → Networks → Tunnels
3. Click Create a tunnel
4. Choose Cloudflared and click Next
5. Name your tunnel (e.g., "knot-server") and click Save tunnel
6. Copy the tunnel token shown (you'll need this)
7. Under Public Hostname, click Add a public hostname:
   • Subdomain: knot (or your choice)
   • Domain: Select your domain
   • Service Type: HTTP
   • URL: localhost:5555
8. Click Save hostname
9. Click Save tunnel

Step 8: Install Tunnel on Your Server#

# Install the tunnel using your token from the dashboard
sudo cloudflared service install YOUR_TUNNEL_TOKEN_HERE

Replace YOUR_TUNNEL_TOKEN_HERE with the token you copied from the dashboard.

# Start the tunnel service
sudo systemctl start cloudflared
sudo systemctl enable cloudflared

# Check status
sudo systemctl status cloudflared

Step 9: Verify Installation#

# Check if knot server is running
curl http://localhost:5555

# Check if tunnel is connected
sudo cloudflared tunnel info

Step 10: Register Your Knot#

1. Go to https://tangled.org/knots
2. Add your knot server hostname (knot.yourdomain.com)
3. Click the verify button to finalize registration

Troubleshooting#

Check knot server logs:#

sudo journalctl -u knotserver -f

Check Cloudflare tunnel logs:#

sudo journalctl -u cloudflared -f

Restart services:#

sudo systemctl restart knotserver
sudo systemctl restart cloudflared

Test local connectivity:#

curl http://localhost:5555

Done!#

Your knot server should now be accessible at https://knot.yourdomain.com. The Cloudflare Tunnel automatically handles:

• SSL/TLS certificates
• DDoS protection
• No need for port forwarding
• WebSocket support for git events

Made with help from Claude Sonnet 4.5