akash-static-template

A ready-to-use template to deploy a static website on Akash Network with automatic builds via GitHub Actions and a custom domain via Cloudflare.

---

What this template does

Every time you push code to GitHub, this template automatically:

1. Builds a Docker image containing your website
2. Pushes it to GitHub's container registry (ghcr.io)
3. Updates deploy.yaml with the new image tag

You then paste deploy.yaml into Akash Console to update your live site.

---

Prerequisites

• A GitHub account → github.com
• A Keplr wallet with AKT tokens → wallet.keplr.app
• A domain name → register one at Namecheap, Gandi or OVH
• Your domain's DNS managed on Cloudflare → cloudflare.com (free plan works)

---

Step 1: Use this template

1. Click the green "Use this template" button at the top of this page
2. Click "Create a new repository"
3. Name your repo (e.g. my-site)
4. Make sure it is Public
5. Click "Create repository"

---

Step 2: Enable workflow permissions

In your new repo:

1. Go to Settings → Actions → General
2. Scroll down to Workflow permissions
3. Select Read and write permissions
4. Click Save

---

Step 3: Add your domain as a secret

In your new repo:

1. Go to Settings → Secrets and variables → Actions
2. Click New repository secret
3. Add this secret:

Name	Value
DOMAIN	yourdomain.com

---

Step 4 — Build your own site

This template uses plain static HTML and CSS no framework, no build tool, no JavaScript required. Static means your site is just files served directly by nginx: fast, simple, and perfectly suited for Akash Network.

Everything lives in the site/ folder. You can completely replace the existing index.html and add any files you want:

site/
├── index.html       ← your main page (required)
├── style.css        ← your styles
├── about.html       ← any additional pages
└── images/          ← your images
    └── photo.jpg

What you can build:

• A personal homepage / bio page
• A portfolio
• A link-in-bio page
• A landing page for a project
• Any site that doesn't need a backend or database

What you cannot do with static hosting:

• User login / authentication
• Forms that send emails (unless you use a third-party service like Formspree)
• Any server-side logic (PHP, Python, Node.js...)

To get started, simply delete the contents of site/index.html and write your own HTML and CSS from scratch or keep the existing design and modify it. Either way, as long as your main file is named index.html, the template will handle the rest automatically.

---

Step 5: Push and wait for the build

Once you save your changes, commit and push:

git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
cd YOUR_REPO
# edit site/index.html
git add .
git commit -m "customize my site"
git push

Then go to the Actions tab of your repo and wait for the workflow to turn green ✅ (takes about 30 seconds).

Once green, run:

git pull

This updates your local deploy.yaml with the new image tag generated by the workflow.

---

Step 6: Make your image public

By default, ghcr.io images are private. Akash needs to pull the image so it must be public.

1. Go to github.com/YOUR_USERNAME → Packages tab
2. Click on your image (same name as your repo)
3. Click Package settings (bottom right)
4. Change visibility → Public → Confirm

You only need to do this once.

---

Step 7: Deploy on Akash

1. Go to console.akash.network
2. Connect your Keplr wallet
3. Click Deploy → From SDL
4. Open your deploy.yaml file, copy its entire content and paste it
5. Click Create Deployment
6. Review the bids from providers and select one
7. Click Accept Bid and confirm the transaction in Keplr
8. Wait for the deployment to start you will see a public URL like xyz.provider.akash.network

Note the public URL you will need it in the next step.

---

Step 8: Configure Cloudflare DNS

1. Log in to cloudflare.com
2. Select your domain
3. Go to DNS → Records
4. Add these two records:

Type	Name	Value	Proxy
CNAME	@	xyz.provider.akash.network	✅ Proxied (orange cloud)
CNAME	www	xyz.provider.akash.network	✅ Proxied (orange cloud)

The orange cloud enables free HTTPS automatically.

DNS changes can take a few minutes to propagate. After that, your site is live at yourdomain.com ✅

---

Updating your site

Every time you want to update your site:

git pull                  # always pull first
# edit site/index.html
git add .
git commit -m "update"
git push

Then wait for the Actions workflow to turn green ✅, run git pull again, and:

1. Go to Akash Console → your deployment
2. Click Update
3. Paste the new content of deploy.yaml
4. Confirm

Your site will reload with the latest version within a few seconds.

---

Common issues

Problem	Cause	Solution
Workflow not triggering	.github/ folder not pushed	Use git add . not git add *
403 on image pull	Image is private on ghcr.io	GitHub profile → Packages → your image → Package settings → set to Public
403 when workflow tries to push	Write permissions not enabled	Settings → Actions → General → Read and write permissions
Site not updating on Akash	Old image tag in deploy.yaml	Run git pull after the workflow finishes, then paste the updated deploy.yaml in Akash Console
Branches diverging on git pull	Workflow pushed while you were editing	Run git config pull.rebase false then git pull

---

Project structure

my-site/
├── site/
│   └── index.html          ← your website (edit this)
├── Dockerfile              ← packages nginx + your site into a Docker image
├── deploy.yaml             ← auto-updated by GitHub Actions, paste into Akash Console
└── .github/
    └── workflows/
        └── deploy.yml      ← automatic build triggered on every git push