From c05c32f70cc3cfaff9ade3da0e05c7556a82c461 Mon Sep 17 00:00:00 2001 From: constantprojects Date: Mon, 23 Feb 2026 16:35:26 -0700 Subject: [PATCH] Polish guide.md for accessibility (iteration 4) - Add itemized cost breakdown in intro step - Explain "root" before SSH step, recommend password managers - Add VPS web console fallback tip - Explain what ssh root@IP means inline - Explain what curl | bash does with link to source code - Add registrar-specific DNS navigation instructions - Add www CNAME record tip - Add dig/dnsutils install hint - Expand dpkg pink/purple screen guidance - Add SSH reconnection tip if connection drops during install - Fix "Going Further" to reference automated (not manual) security setup - Improve password storage callout with Bitwarden/1Password links - Add SMTP pricing details for email services - Describe WordPress dashboard sidebar layout - Explain Ctrl+C key combo for beginners - Add SSH timeout troubleshooting with web console reference - Add GitHub issues link for getting help Co-Authored-By: Claude Opus 4.6 --- guide.md | 54 ++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 42 insertions(+), 12 deletions(-) diff --git a/guide.md b/guide.md index 8365f24..12b9ee3 100644 --- a/guide.md +++ b/guide.md @@ -32,6 +32,13 @@ WebsiteBox packages WordPress with all the security, backups, and server configu - About **45 minutes** of time - A **computer** with internet access (Mac, Windows, or Linux — any will work) +**Estimated total cost:** +- Server hosting: **$3.50-6/month** (billed monthly or annually) +- Domain name: **$1-12/year** (billed annually) +- SSL certificate: **Free** (provided automatically by [Let's Encrypt](https://letsencrypt.org/)) +- WordPress: **Free** (open-source software) +- WebsiteBox: **Free** (open-source) + That's it. No technical background needed. This guide walks you through every single step. [step: Get a Server] @@ -59,14 +66,18 @@ When signing up, you'll be asked to configure your server. Choose these options: After your server is created (usually takes 30-60 seconds), the provider will show you two critical pieces of information: 1. An **IP address** — a set of numbers like `203.0.113.45` that identifies your server on the internet -2. A **root password** — the master password for your server +2. A **root password** — the master password for your server. "Root" is the Linux equivalent of an administrator account — it has full control over the server. -**Save both of these somewhere safe.** You'll need them in the next steps. +**Save both of these somewhere safe** — in a [password manager](https://bitwarden.com/) (recommended), a note on your phone, or written down. You'll need them in the next steps. [callout:tip] Most providers also email you the IP address and password. Check your inbox (and spam folder) if you lose track of them. Some providers like Vultr show them on a "Server Details" page you can return to anytime. [/callout] +[callout:tip] +**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] 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. @@ -109,7 +120,7 @@ Don't worry if you've never done this before — you'll only need to type a few ssh root@YOUR_SERVER_IP [/code] -For example, if your IP address is `203.0.113.45`, you would type: `ssh root@203.0.113.45` +This tells your computer to connect (`ssh`) as the administrator account (`root`) to the server at your IP address. For example, if your IP address is `203.0.113.45`, you would type: `ssh root@203.0.113.45` **On Windows:** @@ -161,6 +172,10 @@ curl -fsSL https://raw.githubusercontent.com/websitebox/websitebox/main/install. **How to paste into a terminal:** On Mac, press `Cmd + V`. On Windows Terminal, right-click. On PuTTY, right-click. On Linux, press `Ctrl + Shift + V`. [/callout] +[callout:info] +**What does this command do?** `curl` is a tool that downloads files from the internet. The URL points to the WebsiteBox install script on [GitHub](https://github.com/websitebox/websitebox) (where the project's code is publicly hosted). The `| bash` part tells your server to run the downloaded script. The entire install script is [open source](https://github.com/websitebox/websitebox/blob/main/install.sh) — you can read every line of it before running it if you want to verify what it does. +[/callout] + This one command does everything needed to prepare your server: 1. **Updates your system** — installs the latest security patches @@ -206,10 +221,14 @@ Cloning WebsiteBox... ═══════════════════════════════════════════════════════════ [/terminal] -The entire process takes 2-3 minutes. If you see a pink/purple screen asking about restarting services during the update, just press **Enter** to accept the defaults. +The entire process takes 2-3 minutes. You might see a pink or purple full-screen prompt asking about restarting services or keeping configuration files — this is normal and comes from the system's package manager. Just press **Enter** to accept the default option each time. If it asks "Which services should be restarted?" just press **Enter**. If it asks about configuration files, press **Enter** to keep the current version. When the "WebsiteBox Setup Wizard" header appears, the installer is done and the setup wizard has started — that's covered in the next step. +[callout:tip] +**What if your SSH connection drops during installation?** If your terminal freezes or disconnects mid-install (bad WiFi, closed laptop, etc.), don't worry. Just reconnect with `ssh root@YOUR_SERVER_IP` and run the install command again. The installer is designed to pick up where it left off — it won't reinstall things that are already set up. +[/callout] + [callout:info] **What just got secured?** The installer automatically set up four layers of protection: - **[UFW firewall](https://wiki.ubuntu.com/UncomplicatedFirewall)** — blocks all network traffic except SSH (so you can connect), HTTP (port 80), and HTTPS (port 443). Everything else is locked down. @@ -260,7 +279,7 @@ WebsiteBox can require visitors to confirm their age before viewing your site. T - Type `n` to disable — visitors go straight to your site **7. SMTP server** (optional) -This lets WordPress send emails (like password resets or contact form notifications). If you don't have an email service set up, just press **Enter** to skip — your site will work fine without it. If you want to set it up later, popular email relay services include [Mailgun](https://www.mailgun.com/) (free tier available), [SendGrid](https://sendgrid.com/) (free tier), and [Amazon SES](https://aws.amazon.com/ses/) (very cheap). +SMTP is the technology that sends emails. This lets WordPress send emails like password resets, contact form notifications, and security alerts. If you don't have an email service set up, just press **Enter** to skip — your site will work perfectly fine without it, and you can always set it up later. Popular email relay services include [Mailgun](https://www.mailgun.com/) (free tier: 1,000 emails/month), [SendGrid](https://sendgrid.com/) (free tier: 100 emails/day), and [Amazon SES](https://aws.amazon.com/ses/) (very cheap at ~$0.10 per 1,000 emails). **8. Backup retention** How many days to keep automatic backups of your site. The default is 30 days, which is a good balance between safety and disk space. @@ -310,7 +329,7 @@ Days to keep local backups (1-365) [30]: [/terminal] [callout:danger] -**If your password was auto-generated, write it down immediately.** It's also saved in a file called `.credentials` inside the websitebox folder. Once you've stored the password somewhere safe (like a password manager), delete that file by running: `rm ~/websitebox/.credentials` +**If your password was auto-generated, save it immediately.** It's also saved in a file called `.credentials` inside the websitebox folder, but you should store it somewhere more permanent. The best option is a **password manager** like [Bitwarden](https://bitwarden.com/) (free) or [1Password](https://1password.com/) — these securely store all your passwords in one place. At minimum, write it down or save it in a note on your phone. Once you've stored the password somewhere safe, delete the file from your server by running: `rm ~/websitebox/.credentials` [/callout] [callout:tip] @@ -326,7 +345,7 @@ This is done by adding a **DNS record** — specifically an **"A record"** — i **How to do it:** 1. Log in to the website where you bought your domain ([Porkbun](https://porkbun.com/), [Namecheap](https://www.namecheap.com/), [Cloudflare](https://dash.cloudflare.com/), etc.) -2. Find your domain and look for **DNS settings**, **DNS records**, or **Manage DNS** — it's usually in the domain's settings page +2. Find your domain and look for **DNS settings**, **DNS records**, or **Manage DNS** — it's usually in the domain's settings page. On Porkbun, click the domain then look for "DNS" in the left menu. On Namecheap, go to your domain list and click "Manage" then "Advanced DNS." On Cloudflare, select your domain and click "DNS" in the sidebar. 3. Look for an existing A record, or click **Add record** / **Add new record** 4. Fill in these values: - **Type:** `A` @@ -335,6 +354,10 @@ This is done by adding a **DNS record** — specifically an **"A record"** — i - **TTL:** Leave as "Auto" or pick the lowest number available (like 300 or 600) 5. Click **Save** or **Add record** +[callout:tip] +**What about `www`?** If you want `www.yourdomain.com` to also work (in addition to `yourdomain.com`), add a second DNS record: Type `CNAME`, Host/Name `www`, Value/Points to `yourdomain.com`. This tells browsers that `www.yourdomain.com` is an alias for your main domain. +[/callout] + [callout:info] **What is DNS propagation?** After you save the record, the change needs to spread across the internet. This is called "propagation" and usually takes 5-30 minutes, though it can occasionally take up to 48 hours. During this time, your domain is being updated across servers worldwide. [/callout] @@ -351,7 +374,7 @@ Replace `yourdomain.com` with your actual domain. The `dig` command looks up whe - **If it shows your server's IP address** (e.g., `203.0.113.45`) — DNS is ready. Proceed to the next step. - **If it shows nothing, or a different IP address** — DNS hasn't propagated yet. Wait 5-10 more minutes and try again. -- **If you see `dig: command not found`** — try `nslookup yourdomain.com` instead, or use the online tool below. +- **If you see `dig: command not found`** — install it with `apt install -y dnsutils`, then try again. Or use `nslookup yourdomain.com` instead, or use the online tool below. [terminal] $ dig myportfolio.art +short @@ -364,7 +387,7 @@ You can also check DNS propagation from your own computer using a free online to [step: Launch Your Website] -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 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`) and run these two commands: [code:bash] cd ~/websitebox @@ -390,7 +413,7 @@ docker compose logs -f 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. -Press `Ctrl+C` to stop watching the logs. **This only stops the log viewer — your website keeps running.** +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: @@ -422,7 +445,7 @@ When you visit your domain, you'll see a clean, minimal website with your site t If you enabled the **age verification gate**, you'll see an age confirmation screen first. This is working as intended. Confirm your age to proceed to the site. You can customize the gate's appearance and wording later inside WordPress under **Settings > Age Gate**. -When you visit `/wp-admin`, you'll see the WordPress login page — a simple form asking for a username and password. Enter the **admin username** and **password** you chose during the setup wizard, and you'll land on the WordPress Dashboard — your site's control center. +When you visit `/wp-admin`, you'll see the WordPress login page — a simple form asking for a username and password. Enter the **admin username** and **password** you chose during the setup wizard, and you'll land on the WordPress Dashboard — your site's control center. The dashboard has a sidebar menu on the left with sections like Posts, Pages, Appearance, Plugins, and Settings. This is where you'll manage everything about your site. [callout:tip] **Bookmark these two URLs:** @@ -621,6 +644,10 @@ docker compose up -d The first command starts Docker itself, and the second starts your website containers. +**You can't connect to your server at all (SSH times out):** + +If `ssh root@YOUR_SERVER_IP` just hangs and eventually says "Connection timed out," your server might be down. Check your VPS provider's dashboard — there's usually a status indicator showing if the server is running. Try rebooting it from the dashboard. If you can't SSH in but the server shows as running, use your provider's **web console** (see the tip in the "Get a Server" step) to access it through your browser. + **Something else is wrong and you need more details:** View the live logs for each part of your website to see what's happening: @@ -675,11 +702,14 @@ When you're ready for search engines to find your site, go to **Settings > Readi A CDN (Content Delivery Network) caches your images and pages on servers around the world, making your site load faster for visitors far from your server. [Cloudflare](https://www.cloudflare.com/) offers a free plan — you just change your domain's nameservers to Cloudflare's. **Harden your server further:** -You already set up a firewall and fail2ban earlier in this guide, which handles the vast majority of threats. For the next level of security, consider setting up [SSH key authentication](https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys-on-ubuntu-22-04) — this lets you log in without a password, using a cryptographic key stored on your computer instead. Once SSH keys are working, you can [disable password login entirely](https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys-on-ubuntu-22-04#step-4-disabling-password-authentication-on-your-server), making brute-force attacks completely impossible. +The installer already set up a firewall and fail2ban, which handles the vast majority of threats. For the next level of security, consider setting up [SSH key authentication](https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys-on-ubuntu-22-04) — this lets you log in without a password, using a cryptographic key stored on your computer instead. Once SSH keys are working, you can [disable password login entirely](https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys-on-ubuntu-22-04#step-4-disabling-password-authentication-on-your-server), making brute-force attacks completely impossible. **Learn more about WordPress:** [WordPress.org's documentation](https://wordpress.org/documentation/) and [WPBeginner](https://www.wpbeginner.com/) are excellent free resources for learning how to get the most out of your site. The [WordPress block editor guide](https://wordpress.org/documentation/article/wordpress-block-editor/) is particularly helpful for learning how to create beautiful page layouts. +**Get help:** +If you run into problems or have questions, you can [open an issue on GitHub](https://github.com/websitebox/websitebox/issues) — that's where the project's developers and community track bugs and feature requests. You can also browse existing issues to see if someone has already had the same question. + [callout:tip] You now own your website infrastructure. Unlike hosted platforms, nobody can take your site down for content policy reasons, raise your prices unexpectedly, or lock you into their ecosystem. Your data lives on your server, and you can move it anywhere. [/callout]