Private
Public Access
1
0

Add --build to websitebox up, comprehensive guide.md polish

- websitebox up now includes --build flag to always rebuild images,
  fixing Docker cache serving stale containers after code updates
- setup.sh launch command updated to source ~/.bashrc first
- guide.md: added step roadmap table with time estimates
- guide.md: added time estimates to all step headers
- guide.md: updated Launch step to use websitebox shortcut with
  source ~/.bashrc, added command reference table
- guide.md: updated all troubleshooting commands to use websitebox
  shortcut instead of cd + docker compose
- guide.md: added 'websitebox: command not found' troubleshooting
- guide.md: updated setup wizard terminal example to match current
  colored output format
- guide.md: added container build step to launch explanation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
constantprojects
2026-02-24 09:18:54 -07:00
parent 6a164ab40d
commit 2c3b58eea7
3 changed files with 126 additions and 67 deletions

189
guide.md
View File

@@ -41,7 +41,21 @@ WebsiteBox packages WordPress with all the security, backups, and server configu
That's it. No technical background needed. This guide walks you through every single step.
[step: Get a Server]
**Here's the roadmap — 7 steps, about 45 minutes total:**
| Step | What You'll Do | Time |
|------|---------------|------|
| 1. Get a Server | Rent a small server from a hosting company | 5 min |
| 2. Get a Domain Name | Buy a web address for your site | 5 min |
| 3. Connect to Your Server | Open a remote connection to your server | 2 min |
| 4. Run the Installer | One command that sets everything up | 5-10 min (mostly waiting) |
| 5. Complete the Setup Wizard | Answer questions about your site | 3 min |
| 6. Point Your Domain | Tell the internet where your site lives | 5 min + wait time |
| 7. Launch Your Website | Start your site with one command | 2-3 min |
After that, you'll visit your live website and learn how to customize it. Let's go.
[step: Get a Server (~5 minutes)]
Before you can have a website, you need somewhere for it to live. That "somewhere" is a **server** — a computer in a data center that stays on 24/7 so your website is always available to visitors.
@@ -78,7 +92,7 @@ Most providers also email you the IP address and password. Check your inbox (and
**Can't connect later?** Most VPS providers have a **web console** (sometimes called "VNC console" or "Recovery console") in their dashboard that lets you access your server through your browser — no SSH needed. Look for a "Console" or "View Console" button on your server's management page. This is useful as a fallback if SSH isn't working.
[/callout]
[step: Get a Domain Name]
[step: Get a Domain Name (~5 minutes)]
A **domain name** is your website's address — like `myportfolio.com` or `janedoe.art`. This is what people type into their browser to find your site.
@@ -105,7 +119,7 @@ You don't need to configure anything on the domain yet — just have it purchase
If you're building a portfolio or creative site, consider fun extensions like `.art`, `.studio`, `.design`, or `.gallery` — they're often cheaper than `.com` and more memorable.
[/callout]
[step: Connect to Your Server]
[step: Connect to Your Server (~2 minutes)]
Now you need to connect to your server so you can set things up. You'll do this using **SSH** (Secure Shell) — think of it as a secure remote control for your server. Instead of a graphical desktop, you type commands into a text window.
@@ -160,7 +174,7 @@ When typing a password in the terminal, **nothing appears on screen** — no dot
If you get "Connection refused" or "Connection timed out," wait a minute — your server might still be starting up. Try again after 60 seconds. If it still doesn't work, double-check the IP address.
[/callout]
[step: Run the Installer]
[step: Run the Installer (~5-10 minutes)]
Now for the easy part. Copy and paste this single command into your terminal and press Enter:
@@ -220,7 +234,8 @@ Installing Docker...
This is the largest download — usually takes 1-3 minutes.
Docker installation complete.
Cloning WebsiteBox...
Downloading the project files from GitHub. Just a few seconds.
Downloading the project files. Just a few seconds.
Added 'websitebox' command
═══════════════════════════════════════════════════════════
WebsiteBox Setup Wizard
@@ -251,7 +266,7 @@ When the "WebsiteBox Setup Wizard" header appears, the installer is done and the
`sudo` is a command that gives you administrator access. You may be asked to enter your password again.
[/callout]
[step: Complete the Setup Wizard]
[step: Complete the Setup Wizard (~3 minutes)]
The installer automatically launches an interactive setup wizard. It will ask you a series of questions to configure your website. Here's exactly what to expect, question by question:
@@ -306,30 +321,46 @@ WordPress admin username: janedoe
Admin email (used for SSL & WordPress): jane@email.com
Set your WordPress admin password.
Press Enter to auto-generate a secure 20-character password.
Press Enter to auto-generate a secure 20-character password.
Note: your password won't appear on screen as you type — that's normal.
Admin password:
Confirm password:
✓ Password set.
Enable age verification gate? (Y/n): Y
Minimum age (18-21) [18]: 18
SMTP server (optional, press Enter to skip):
SMTP server (if you don't know what this is, press Enter to skip):
Days to keep local backups (1-365) [30]:
═══════════════════════════════════════════════════════════
WebsiteBox Setup Complete!
═══════════════════════════════════════════════════════════
Configuration saved to .env
Configuration saved to .env
Next steps:
1. Point your domain's A record to this server's IP: 203.0.113.45
2. Wait for DNS propagation (check: dig myportfolio.art)
3. Run: docker compose up -d
4. Access your site at: https://myportfolio.art
5. Log in at: https://myportfolio.art/wp-admin
Username: janedoe
Password: ******* (the password you set during setup)
1. Point your domain's A record to this server
Type: A
Name: @ (this means the root domain, e.g., myportfolio.art)
Value: 203.0.113.45 (your server's IP address)
TTL: Auto (or the lowest option available)
2. Wait for DNS propagation, then verify it's working
dig myportfolio.art +short
✓ Success looks like: 203.0.113.45
✗ Not ready yet: (blank output — wait and try again)
3. Launch your website
source ~/.bashrc && websitebox up
4. Visit your site
Your website: https://myportfolio.art
Admin login: https://myportfolio.art/wp-admin
Username: janedoe
Password: (the password you set during setup)
═══════════════════════════════════════════════════════════
[/terminal]
@@ -342,7 +373,7 @@ Days to keep local backups (1-365) [30]:
The setup wizard summary shows your server's IP address and the next steps. It's a good idea to take a screenshot of this screen or copy the text for reference.
[/callout]
[step: Point Your Domain to Your Server]
[step: Point Your Domain to Your Server (~5 minutes + wait time)]
Right now, your domain name and your server don't know about each other. You need to create a connection between them so that when someone types your domain into a browser, the internet knows to send them to your server.
@@ -391,30 +422,38 @@ $ dig myportfolio.art +short
You can also check DNS propagation from your own computer using a free online tool like [whatsmydns.net](https://www.whatsmydns.net/) — type in your domain and see if servers around the world are returning your IP address.
[/callout]
[step: Launch Your Website]
[step: Launch Your Website (~2-3 minutes)]
This is the moment everything comes together. Make sure DNS is pointing to your server (you verified this in the previous step), then SSH into your server (if you disconnected, reconnect with `ssh root@YOUR_SERVER_IP`) and run these two commands:
This is the moment everything comes together. Make sure DNS is pointing to your server (you verified this in the previous step), then SSH into your server (if you disconnected, reconnect with `ssh root@YOUR_SERVER_IP`).
First, activate the `websitebox` shortcut command that the installer added for you:
[code:bash]
cd ~/websitebox
docker compose up -d
source ~/.bashrc
[/code]
Here's what each part means:
- `cd ~/websitebox``cd` means "change directory" (like opening a folder). The `~` symbol is a shortcut for your home folder. So this navigates to the WebsiteBox project folder.
- `docker compose up -d` — This tells [Docker](https://www.docker.com/) to start all the services that make up your website. The `-d` flag means "detached" — your site keeps running in the background even after you close the terminal window.
(`source` reloads your shell configuration so the new `websitebox` command becomes available. You only need to do this once — it'll work automatically in future SSH sessions.)
Now launch your website with a single command:
[code:bash]
websitebox up
[/code]
That's it. This one command navigates to the project folder, builds any updated container images, and starts all the services in the background.
Here's what happens automatically behind the scenes:
1. **Database starts** — [MariaDB](https://mariadb.org/) (a database server) starts up to store your website's content
2. **WordPress installs** — [WordPress](https://wordpress.org/) is set up with your chosen title, username, and plugins
3. **SSL certificate acquired** — A free security certificate from [Let's Encrypt](https://letsencrypt.org/) is obtained so your site gets the padlock icon in browsers
4. **Web server configured** — [Nginx](https://nginx.org/) (the web server) starts serving your site to visitors
1. **Container images build** — Docker builds the nginx and WordPress containers from the project files. You'll see lines like `Building nginx...` and `Building wordpress...` scrolling by. On the first run, this downloads base images and can take 1-2 minutes.
2. **Database starts** — [MariaDB](https://mariadb.org/) (a database server) starts up to store your website's content
3. **WordPress installs** — [WordPress](https://wordpress.org/) is set up with your chosen title, username, and plugins
4. **SSL certificate acquired** — A free security certificate from [Let's Encrypt](https://letsencrypt.org/) is obtained so your site gets the padlock icon in browsers
5. **Web server configured** — [Nginx](https://nginx.org/) (the web server) starts serving your site to visitors
The first launch takes 2-3 minutes as everything downloads and configures. You can watch the real-time progress by running:
[code:bash]
docker compose logs -f
websitebox logs
[/code]
You'll see messages scrolling by about each service starting up. When you see lines like `WebsiteBox: First-run setup complete!` and `SSL certificate acquired successfully!`, everything is ready.
@@ -422,16 +461,34 @@ You'll see messages scrolling by about each service starting up. When you see li
Press `Ctrl+C` to stop watching the logs (hold the `Ctrl` key and press the `C` key). **This only stops the log viewer — your website keeps running.**
[callout:info]
**If you see a "Setting up SSL..." page** when you visit your site, it means DNS hasn't fully propagated yet. This is not an error — just wait a few more minutes for DNS to finish updating, then run this command to retry:
**If you see a "Setting up SSL..." page** when you visit your site, it means the SSL certificate hasn't been issued yet — usually because DNS hasn't fully propagated. This is not an error. Wait a few more minutes for DNS to finish updating, then tell the web server to retry:
`docker compose restart nginx`
`websitebox restart nginx`
The SSL certificate will be obtained automatically once DNS is working.
[/callout]
[callout:tip]
**Quick reference — `websitebox` commands you can use from anywhere:**
| Command | What it does |
|---------|-------------|
| `websitebox up` | Start your site (builds and runs everything) |
| `websitebox down` | Stop your site |
| `websitebox logs` | Watch live logs from all services |
| `websitebox logs nginx` | Watch logs from one specific service |
| `websitebox restart nginx` | Restart one service |
| `websitebox ps` | Show status of all containers |
These are shortcuts for `docker compose` commands that automatically navigate to the project folder first. You can run them from any directory on your server.
[/callout]
[callout:tip]
After the first launch, you can always check that everything is running properly with:
`./scripts/healthcheck.sh`
[code:bash]
cd ~/websitebox && ./scripts/healthcheck.sh
[/code]
You should see `[OK]` next to each service.
[/callout]
@@ -522,13 +579,10 @@ That said, there are a few simple maintenance tasks worth doing occasionally. Al
**Check that everything is running smoothly:**
[code:bash]
cd ~/websitebox
./scripts/healthcheck.sh
cd ~/websitebox && ./scripts/healthcheck.sh
[/code]
(The `./` at the start means "run this file from the current folder." You'll see this in front of all the script commands below.)
This checks all parts of your website and reports their status. You want to see `[OK]` next to each service:
This checks all four parts of your website and reports their status. You want to see `[OK]` next to each service:
[terminal]
═══════════════════════════════════════════════════════════
@@ -542,11 +596,12 @@ This checks all parts of your website and reports their status. You want to see
All services are healthy.
[/terminal]
If any service shows a problem, see the Troubleshooting step below.
**Update WebsiteBox** (when new versions are released):
[code:bash]
cd ~/websitebox
./scripts/update.sh
cd ~/websitebox && ./scripts/update.sh
[/code]
This shows you what changed, asks for confirmation, then updates everything safely. It pulls the latest improvements, rebuilds the containers, and verifies that your site is still healthy afterward.
@@ -554,18 +609,17 @@ This shows you what changed, asks for confirmation, then updates everything safe
**Create a manual backup before making big changes:**
[code:bash]
cd ~/websitebox
./scripts/backup.sh
cd ~/websitebox && ./scripts/backup.sh
[/code]
This creates a snapshot of your database and all your website files, saved in the `websitebox-data/backups/` folder on your server. Good practice before updating WordPress or installing new plugins.
**Update WordPress itself, plugins, and themes:**
This happens inside your browser, not the terminal. Log in to `https://yourdomain.com/wp-admin`, and when updates are available, you'll see a red notification badge. Go to **Dashboard > Updates** and click the update buttons.
This happens inside your browser, not the terminal. Log in to `https://yourdomain.com/wp-admin`, and when updates are available, you'll see a red notification badge on the left sidebar. Go to **Dashboard > Updates** and click the update buttons. WordPress will download and apply the updates automatically.
[callout:warning]
**Before running WordPress updates** through the admin dashboard, it's smart to create a backup first: SSH into your server and run `./scripts/backup.sh`. That way, if an update causes problems, you have a recent copy to fall back on.
**Before running WordPress updates** through the admin dashboard, it's smart to create a backup first: SSH into your server and run `cd ~/websitebox && ./scripts/backup.sh`. That way, if an update causes problems, you have a recent copy to fall back on.
[/callout]
[callout:tip]
@@ -585,41 +639,37 @@ This means the SSL certificate hasn't been issued yet, usually because DNS isn't
3. Once DNS is correct, tell the web server to retry:
[code:bash]
cd ~/websitebox
docker compose restart nginx
websitebox restart nginx
[/code]
**You see "Error establishing a database connection":**
The database may still be starting up (especially right after a first launch or reboot). Wait one minute and refresh the page. If it persists:
The database may still be starting up (especially right after a first launch or reboot). Wait one minute and refresh the page. If it persists, check the status of your containers:
[code:bash]
cd ~/websitebox
docker compose ps
websitebox ps
[/code]
This shows the status of each container. All services should show "Up" and "healthy." If the `db` service is missing or unhealthy, try restarting everything:
[code:bash]
docker compose restart
websitebox restart
[/code]
**You forgot your WordPress admin password:**
No problem — you can reset it directly from the server terminal. The command is long but straightforward. Just replace two things:
No problem — you can reset it directly from the server terminal. The command is long but straightforward — just copy it and swap in your details. Replace two things:
- `YOUR_USERNAME` — your WordPress admin username (the one you chose during setup)
- `NEW_PASSWORD` — whatever you want your new password to be
[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
websitebox exec wordpress su -s /bin/sh -c "wp user update YOUR_USERNAME --user_pass='NEW_PASSWORD' --path=/var/www/html" www-data
[/code]
**Worked example:** If your username is `janedoe` and you want to change your password to `MyNewSecurePass123`, the command would look like this:
**Worked example:** If your username is `janedoe` and you want to change your password to `MyNewSecurePass123`:
[code:bash]
cd ~/websitebox
docker compose exec wordpress su -s /bin/sh -c "wp user update janedoe --user_pass='MyNewSecurePass123' --path=/var/www/html" www-data
websitebox exec wordpress su -s /bin/sh -c "wp user update janedoe --user_pass='MyNewSecurePass123' --path=/var/www/html" www-data
[/code]
After running the command, you can immediately log in at `https://yourdomain.com/wp-admin` with the new password.
@@ -628,6 +678,16 @@ After running the command, you can immediately log in at `https://yourdomain.com
This command looks complicated, but you don't need to understand how it works — just copy it, swap in your username and new password, and paste it into the terminal. The command reaches inside the WordPress container and uses [WP-CLI](https://wp-cli.org/) (a WordPress command-line tool) to update your password.
[/callout]
**`websitebox: command not found`:**
This happens when the `websitebox` shell command hasn't been loaded yet in your current terminal session. Run this to activate it:
[code:bash]
source ~/.bashrc
[/code]
Then try your command again (e.g., `websitebox up`). In future SSH sessions, the command will work automatically — you only need to run `source` once after the initial install.
**"Permission denied" when running Docker commands:**
This means your user account doesn't have permission to use Docker. Fix it by running:
@@ -636,7 +696,7 @@ This means your user account doesn't have permission to use Docker. Fix it by ru
sudo usermod -aG docker $USER
[/code]
Then **log out and log back in** (close your SSH connection and reconnect). The command adds your user to the "docker" group, but it only takes effect after a fresh login.
Then **log out and log back in** (close your SSH connection and reconnect with `ssh root@YOUR_SERVER_IP`). The command adds your user to the "docker" group, but it only takes effect after a fresh login.
**Your site is down after a server reboot:**
@@ -644,8 +704,7 @@ Docker should restart automatically, but if it doesn't:
[code:bash]
sudo systemctl start docker
cd ~/websitebox
docker compose up -d
websitebox up
[/code]
The first command starts Docker itself, and the second starts your website containers.
@@ -659,29 +718,29 @@ If `ssh root@YOUR_SERVER_IP` just hangs and eventually says "Connection timed ou
View the live logs for each part of your website to see what's happening:
[code:bash]
cd ~/websitebox
docker compose logs -f nginx
websitebox logs nginx
[/code]
Replace `nginx` with `wordpress` or `db` to see logs for those services instead. Press `Ctrl+C` to stop watching.
Replace `nginx` with `wordpress` or `db` to see logs for those services instead. Press `Ctrl+C` to stop watching. To see logs from all services at once, just run `websitebox logs`.
**Nuclear option — start completely fresh:**
If nothing else works and you want to reset your entire website (this **deletes all your content, pages, and uploads**):
[code:bash]
websitebox down
cd ~/websitebox
docker compose down
rm -rf websitebox-data/
./setup.sh
docker compose up -d
websitebox up
[/code]
Here's what each line does:
- `docker compose down` — stops and removes all the website containers
- `websitebox down` — stops and removes all the website containers
- `cd ~/websitebox` — navigate to the project folder (needed for the next commands)
- `rm -rf websitebox-data/` — deletes all website data (database, uploads, certificates). **This is irreversible.**
- `./setup.sh` — re-runs the setup wizard so you can configure everything fresh
- `docker compose up -d` — starts the website again from scratch
- `websitebox up` — starts the website again from scratch
[callout:danger]
The "nuclear option" above **permanently deletes all your website content**. Only use it as a last resort. Always try the other fixes first, and if possible, run `./scripts/backup.sh` before wiping anything.

View File

@@ -258,7 +258,7 @@ if ! grep -qF 'websitebox()' "$SHELL_RC" 2>/dev/null; then
websitebox() {
cd ~/websitebox || return
case "$1" in
up) shift; docker compose up -d "$@" ;;
up) shift; docker compose up -d --build "$@" ;;
logs) shift; docker compose logs -f "$@" ;;
*) docker compose "$@" ;;
esac

View File

@@ -289,7 +289,7 @@ printf " ${GREEN}✓ Success looks like:${RESET} ${BOLD}${SERVER_IP}${RESET}
printf " ${RED}✗ Not ready yet:${RESET} ${DIM}(blank output or a different IP — wait a few minutes and try again)${RESET}\n\n"
printf " ${BLUE}3.${RESET} ${BOLD}Launch your website${RESET}\n"
printf " Once DNS is working, copy this command into the server terminal:\n\n"
printf " ${CYAN}websitebox up${RESET}\n\n"
printf " ${CYAN}source ~/.bashrc && websitebox up${RESET}\n\n"
printf " ${BLUE}4.${RESET} ${BOLD}Visit your site${RESET}\n"
printf " Your website: ${CYAN}https://${DOMAIN}${RESET}\n"
printf " Admin login: ${CYAN}https://${DOMAIN}/wp-admin${RESET}\n"