Add deployment guide and fix stale README theme listing
- 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
319
guide.md
Normal file
319
guide.md
Normal 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]
|
||||
Reference in New Issue
Block a user