tankadmin/websitebox
Private
Public Access
1
0
Fork 0
Code Pull Requests Releases Activity

Add deployment guide and fix stale README theme listing

Browse Source 
- Create guide.md: step-by-step deployment guide in ProjectPublic
  markup format, written for non-technical users
- Add guide-format.txt: markup syntax reference
- Fix README.md: remove references to deleted templates/ and parts/
  directories in theme tree listing

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
constantprojects
2026-02-23 14:34:04 -07:00
parent a440026701
commit 43e0353224
3 changed files with 462 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

5
README.md
View File

@@ -77,9 +77,8 @@ WebsiteBox uses a child theme built on [GeneratePress](https://generatepress.com
websitebox-data/wordpress/wp-content/themes/websitebox/
├── style.css # Custom styles
├── functions.php # Theme functions
├── theme.json # Block theme settings (colors, typography)
├── templates/ # Block templates
└── parts/ # Template parts (header, footer)
├── index.php # Main template (inherits from GeneratePress)
└── theme.json # Theme settings (colors, typography)
```
### Plugins

141
guide-format.txt Normal file
View File

@@ -0,0 +1,141 @@
ProjectPublic Markup Syntax — Complete Reference
Document Structure
Every document has two parts: frontmatter (metadata) and steps (content).
Frontmatter
Must be the first thing in the document, delimited by ---:
---
title: Your Project Title Here
summary: A brief 1-2 sentence description of what this guide covers
tags: Docker, Linux, Networking
difficulty: beginner
time: 45 minutes
prerequisites: Basic Linux knowledge, SSH access
video: https://youtube.com/watch?v=example
---
Required fields:
- title — project title (max 120 chars)
- summary — short description (max 280 chars)
- tags — comma-separated list (at least 1)
- difficulty — one of: beginner, intermediate, advanced
Optional fields:
- time — estimated time (e.g., "45 minutes", "2 hours")
- prerequisites — comma-separated list
- video — URL to an accompanying video
Steps
Each step starts with [step: Step Title] on its own line:
[step: Install Docker]
Content goes here...
[step: Configure the Container]
More content...
At least one step is required. Steps are numbered automatically (1, 2, 3...).
Element Types (within steps)
1. Text (Markdown)
Plain text between block tags is treated as Markdown. Supports standard Markdown:
This is a paragraph with **bold**, *italic*, and `inline code`.
- Bullet list item
- Another item
1. Numbered list
2. Second item
[Links work like this](https://example.com)
> Blockquotes work too
2. Code Block
[code:bash | install.sh]
sudo apt update
sudo apt install docker.io
systemctl enable --now docker
[/code]
- Syntax: [code:language | filename]...[/code]
- language — syntax highlighting language (e.g., bash, python, yaml, json, javascript, dockerfile)
- | filename — optional, displayed as a tab/label above the code
- Both are optional: [code]...[/code] works with no language or filename
3. Terminal Output
[terminal]
$ docker ps
CONTAINER ID IMAGE STATUS
a1b2c3d4e5f6 nginx Up 2 hours
[/terminal]
- Syntax: [terminal]...[/terminal]
- Used for showing expected command output, logs, or interactive terminal sessions
- Rendered with a terminal-style dark background
4. Callout
[callout:info]
Docker must be running before you proceed to the next step.
[/callout]
[callout:warning]
This will delete all existing containers. Back up your data first.
[/callout]
[callout:danger]
Never run this command on a production server without testing first.
[/callout]
[callout:tip]
You can add this to your .bashrc to make it permanent.
[/callout]
- Syntax: [callout:variant]...[/callout]
- Variants: info, warning, danger, tip
- Content inside supports Markdown
5. Image
[image: https://example.com/screenshot.png | Screenshot of the dashboard]
- Syntax: [image: url | caption]
- url — image source URL (required)
- | caption — optional, used as both alt text and caption
6. Video
[video: https://example.com/demo.mp4]
- Syntax: [video: url]
- Accepts direct video URLs (MP4, WebM)
7. URL Embed
[url: https://github.com/example/repo]
- Syntax: [url: href]
- Renders as a linkcard/embed
--
Notes for Guide Authors
- Every block tag ([code], [terminal], [callout]) must have a matching closing tag ([/code],
[/terminal], [/callout])
- [image], [video], and [url] are self-closing (no closing tag needed)
- Standard Markdown links [text](url) work in text sections and are not confused with block tags
- Frontmatter fields use key: value syntax (one per line, no nesting)
- The parser round-trips: markup → JSON → markup without data loss

319
guide.md Normal file
View File

@@ -0,0 +1,319 @@
---
title: Deploy Your Own Website with WebsiteBox
summary: Go from zero to a live, SSL-secured WordPress website on your own server. No coding required.
tags: WordPress, Docker, Self-Hosting, VPS
difficulty: beginner
time: 45 minutes
prerequisites: A credit card for VPS hosting, A domain name
---
[step: Get a Server]
You need a server (called a "VPS") to host your website. This is a computer in a data center that runs 24/7 so your site is always online. It typically costs $3.50-6/month.
**Recommended providers:**
- **BuyVM** — $3.50/mo, great for all content types, free DDoS protection
- **Vultr** — $6/mo, widely used, straightforward signup
- **OVHcloud** — $5.50/mo, European-based
When signing up, choose these options:
- **Operating system:** Ubuntu 22.04 or Ubuntu 24.04 (either works)
- **Plan size:** At least 1 GB RAM (2 GB recommended)
- **Location:** Whichever is closest to your audience
After your server is created, the provider will show you an **IP address** (looks like `203.0.113.45`) and a **root password**. Save both of these — you'll need them shortly.
[callout:tip]
Most providers send the IP address and password to your email as well. Check your inbox if you lose track of them.
[/callout]
[step: Get a Domain Name]
If you don't already have a domain name, buy one from a registrar like [Namecheap](https://namecheap.com), [Porkbun](https://porkbun.com), or [Cloudflare Registrar](https://www.cloudflare.com/products/registrar/).
You'll configure the domain to point to your server in a later step. For now, just have the domain ready.
[callout:info]
You don't need to configure anything on the domain yet. Just have it purchased and accessible in your registrar's dashboard.
[/callout]
[step: Connect to Your Server]
You'll connect to your server using **SSH**, which gives you a text-based remote control of the server.
**On Mac or Linux**, open the Terminal app and type:
[code:bash]
ssh root@YOUR_SERVER_IP
[/code]
Replace `YOUR_SERVER_IP` with the IP address from your VPS provider (e.g., `ssh root@203.0.113.45`).
**On Windows**, download and open [PuTTY](https://putty.org/) or use Windows Terminal, then connect the same way.
The first time you connect, you'll see a message asking if you trust this server. Type `yes` and press Enter. Then enter the root password from your VPS provider.
[terminal]
$ ssh root@203.0.113.45
The authenticity of host '203.0.113.45' can't be established.
Are you sure you want to continue connecting? (yes/no) yes
root@203.0.113.45's password: ********
Welcome to Ubuntu 22.04
root@my-server:~#
[/terminal]
You're now connected. Everything you type runs on the server, not your own computer.
[callout:tip]
When typing a password in the terminal, no characters will appear on screen — not even dots. This is normal. Just type the password and press Enter.
[/callout]
[step: Run the Installer]
Copy and paste this single command into your terminal:
[code:bash]
curl -fsSL https://raw.githubusercontent.com/websitebox/websitebox/main/install.sh | bash
[/code]
This does three things automatically:
1. Installs Docker (the software that runs your website)
2. Downloads WebsiteBox
3. Launches the setup wizard
You'll see output scrolling by as it installs. This takes 1-2 minutes.
[callout:warning]
If you get a "permission denied" error, try adding `sudo` in front:
`sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/websitebox/websitebox/main/install.sh)"`
This runs the installer with administrator privileges.
[/callout]
[step: Complete the Setup Wizard]
The installer automatically starts a setup wizard that asks you a few questions. Here's what to expect:
**Domain name** — Enter your domain without `https://` or `www`. For example: `example.com`
**Site title** — The name of your website (you can change this later). Press Enter to use the default "My Portfolio."
**Admin username** — Choose a username for your WordPress admin account. Don't use "admin" — pick something unique.
**Admin email** — Your email address. This is used for SSL certificates and WordPress notifications.
**Admin password** — Choose a strong password (12+ characters), or press Enter to auto-generate a secure one. If auto-generated, the password will be displayed on screen and saved to a file — write it down.
**Age verification** — Choose whether visitors must confirm their age before viewing your site. Press Enter for yes, or type `n` to skip.
**SMTP server** — Optional email sending. Press Enter to skip this for now (you can set it up later).
**Backup retention** — How many days to keep backups. Press Enter to use the default (30 days).
[terminal]
Domain name (e.g., example.com): mysite.com
Site title [My Portfolio]: My Art Portfolio
WordPress admin username: jackie
Admin email (used for SSL & WordPress): jackie@email.com
Admin password: ********
Enable age verification gate? (Y/n): Y
Minimum age (18-21) [18]: 18
SMTP server (optional, press Enter to skip):
Days to keep local backups (1-365) [30]:
[/terminal]
When the wizard finishes, you'll see a summary with your server's IP address and a reminder of next steps.
[callout:danger]
If your password was auto-generated, **write it down immediately.** It's also saved in a `.credentials` file in the websitebox folder. Delete that file once you've stored the password somewhere safe.
[/callout]
[step: Point Your Domain to Your Server]
Now you need to tell the internet that your domain should go to your server. This is done by setting a **DNS A record**.
1. Log in to your domain registrar (Namecheap, Porkbun, Cloudflare, etc.)
2. Find the **DNS settings** or **DNS records** page for your domain
3. Add or edit an **A record** with these values:
- **Host / Name:** `@` (this means the root domain)
- **Type:** `A`
- **Value / Points to:** Your server's IP address (e.g., `203.0.113.45`)
- **TTL:** Automatic (or the lowest option available)
4. Save the record
[callout:info]
DNS changes can take anywhere from 5 minutes to 48 hours to take effect worldwide, though it usually happens within 15-30 minutes. You can check progress by typing `dig yourdomain.com` in your server terminal — when it shows your server's IP address, you're ready.
[/callout]
[step: Launch Your Website]
Once DNS is pointing to your server (you checked with `dig` or just waited 30 minutes), SSH back into your server if you disconnected and run:
[code:bash]
cd ~/websitebox
docker compose up -d
[/code]
This starts your entire website. Behind the scenes, it:
- Starts the database
- Installs WordPress with your chosen settings
- Gets a free SSL certificate (the padlock icon in browsers)
- Configures the web server
The first launch takes 2-3 minutes. You can watch the progress with:
[code:bash]
docker compose logs -f
[/code]
Press `Ctrl+C` to stop watching logs (this doesn't stop your site).
[callout:info]
If you see a "Setting up SSL..." page when visiting your site, DNS hasn't finished propagating yet. Wait a few more minutes, then run `docker compose restart nginx` to retry.
[/callout]
[step: Visit Your Site]
Open your browser and go to:
- **Your website:** `https://yourdomain.com`
- **Admin dashboard:** `https://yourdomain.com/wp-admin`
Log in with the admin username and password you chose during setup.
If you enabled age verification, you'll see the age gate before the site content. This is working as intended — visitors need to confirm their age first.
[callout:tip]
Bookmark your admin URL (`https://yourdomain.com/wp-admin`). This is where you'll manage your site going forward — add content, change the look, install plugins, etc.
[/callout]
[step: Customize Your Site]
All customization happens inside the WordPress admin dashboard. Here's where to find things:
**To change how your site looks:**
Go to **Appearance > Customize**. Here you can change colors, fonts, your logo, and the layout.
**To add content:**
Go to **Posts > Add New** for blog posts, or **Pages > Add New** for standalone pages (like an About page or a gallery).
**To upload images:**
Go to **Media > Add New**, or upload images directly while creating a post or page.
**To manage plugins:**
Go to **Plugins** in the sidebar. WebsiteBox comes with three plugins pre-installed:
- **Wordfence** — Security firewall (keeps your site safe)
- **UpdraftPlus** — Automatic backups
- **Age Gate** — Age verification (can be turned on/off under **Settings > Age Gate**)
You can install additional plugins via **Plugins > Add New**.
[callout:tip]
Spend some time exploring the **Appearance > Customize** screen. You can preview changes in real time before publishing them. The GeneratePress theme that WebsiteBox uses is lightweight and fast, with plenty of built-in customization options.
[/callout]
[step: Keep Your Site Running]
Your website is designed to run unattended. It automatically:
- Renews your SSL certificate before it expires
- Restarts itself if the server reboots
- Backs up your data on a regular schedule
Here are the few maintenance tasks you may want to do occasionally:
**Check that everything is healthy:**
[code:bash]
cd ~/websitebox
./scripts/healthcheck.sh
[/code]
**Update WebsiteBox** (when new versions are released):
[code:bash]
cd ~/websitebox
./scripts/update.sh
[/code]
This pulls the latest improvements, rebuilds the containers, and checks that everything is working.
**Create a manual backup:**
[code:bash]
cd ~/websitebox
./scripts/backup.sh
[/code]
Backups are stored in the `websitebox-data/backups/` folder on your server.
**Update WordPress, plugins, and themes:**
Log in to your WordPress admin dashboard. When updates are available, you'll see a notification. Go to **Dashboard > Updates** and click the update buttons.
[callout:warning]
Before updating WordPress core or plugins through the admin dashboard, it's a good idea to run `./scripts/backup.sh` first. That way you can recover if an update causes problems.
[/callout]
[step: Troubleshooting]
If something goes wrong, here are the most common fixes:
**Your site shows "Setting up SSL..." and it won't go away:**
Your domain's DNS isn't pointing to your server yet. Double-check the A record in your registrar's dashboard, wait for it to propagate, then run:
[code:bash]
cd ~/websitebox
docker compose restart nginx
[/code]
**You see "Error establishing a database connection":**
The database container may still be starting up. Wait a minute and refresh. If it persists, check that all containers are running:
[code:bash]
cd ~/websitebox
docker compose ps
[/code]
**You forgot your admin password:**
You can reset it from the server:
[code:bash]
cd ~/websitebox
docker compose exec wordpress su -s /bin/sh -c "wp user update YOUR_USERNAME --user_pass='NEW_PASSWORD' --path=/var/www/html" www-data
[/code]
Replace `YOUR_USERNAME` and `NEW_PASSWORD` with your actual values.
**"Permission denied" when running docker commands:**
Run this, then log out and back in:
[code:bash]
sudo usermod -aG docker $USER
[/code]
**Containers won't start after a server reboot:**
[code:bash]
sudo systemctl start docker
cd ~/websitebox
docker compose up -d
[/code]
**View detailed logs for a specific service:**
[code:bash]
cd ~/websitebox
docker compose logs -f nginx
docker compose logs -f wordpress
docker compose logs -f db
[/code]
[callout:tip]
If you're stuck and none of these fixes help, you can start completely fresh without losing your VPS. Run `docker compose down`, delete the `websitebox-data/` folder, run `./setup.sh` again, and then `docker compose up -d`. This resets your website but keeps the server itself intact.
[/callout]