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

Enhance guide.md for non-technical audiences

Browse Source 
- Add detailed explanations of every concept (VPS, SSH, DNS, Docker)
- Add hyperlinks to all external tools and services
- Expand setup wizard walkthrough with full terminal output example
- Add concrete examples for each wizard prompt
- Add tips for common gotchas (paste shortcuts, invisible passwords, etc.)
- Expand troubleshooting with worked examples
- Add plugin descriptions and links (Wordfence, UpdraftPlus, Age Gate)
- Add healthcheck expected output example
- Add monthly maintenance recommendation

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
constantprojects
2026-02-23 14:44:02 -07:00
parent 43e0353224
commit 0f927f1a17
1 changed files with 354 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

468
guide.md
View File

@@ -1,240 +1,430 @@
---
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.
summary: Go from zero to a live, SSL-secured WordPress website on your own server. No coding or technical experience required.
tags: WordPress, Docker, Self-Hosting, VPS
difficulty: beginner
time: 45 minutes
prerequisites: A credit card for VPS hosting, A domain name
prerequisites: A credit card for VPS hosting ($3.50-6/month), A domain name ($1-12/year)
---
[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.
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.
**Recommended providers:**
You'll rent one from a hosting company. In the industry, these are called a **VPS** (Virtual Private Server). Think of it like renting a small apartment in a big building — you get your own private space on a shared machine. It typically costs between $3.50 and $6 per month.
- **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
**Recommended providers (click to sign up):**
When signing up, choose these options:
- [BuyVM](https://buyvm.net/) — $3.50/mo, most affordable, great for all content types, includes free DDoS protection
- [Vultr](https://www.vultr.com/) — $6/mo, very beginner-friendly dashboard, widely used
- [OVHcloud](https://www.ovhcloud.com/en/vps/) — $5.50/mo, European-based, good for EU audiences
- **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
[callout:info]
All three providers are reliable and will work well. If you're unsure, **BuyVM** is the best value and **Vultr** has the most beginner-friendly interface.
[/callout]
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.
When signing up, you'll be asked to configure your server. Choose these options:
- **Operating system:** Ubuntu 22.04 or Ubuntu 24.04 (these are versions of Linux, the operating system your server will run — either one works fine)
- **Plan size:** At least 1 GB RAM, 2 GB recommended (this is the server's memory — more means better performance)
- **Server location:** Pick whichever city is geographically closest to where most of your visitors will be
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
**Save both of these somewhere safe.** You'll need them in the next steps.
[callout:tip]
Most providers send the IP address and password to your email as well. Check your inbox if you lose track of them.
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]
[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/).
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.
You'll configure the domain to point to your server in a later step. For now, just have the domain ready.
If you don't already have one, you can buy a domain from a **registrar** (a company that sells domain names). Domains typically cost $1-12 per year depending on the extension (.com, .art, .io, etc.).
**Recommended registrars (click to browse):**
- [Porkbun](https://porkbun.com/) — Low prices, very simple interface, great for beginners
- [Namecheap](https://www.namecheap.com/) — Large selection, frequent sales
- [Cloudflare Registrar](https://www.cloudflare.com/products/registrar/) — No markup on prices (charges exactly what the registry charges)
To buy a domain:
1. Go to any registrar's website
2. Search for the name you want (e.g., "myportfolio")
3. Pick an available option and extension (.com, .art, .net, etc.)
4. Complete the purchase
[callout:info]
You don't need to configure anything on the domain yet. Just have it purchased and accessible in your registrar's dashboard.
You don't need to configure anything on the domain yet — just have it purchased and accessible in your registrar's dashboard. We'll connect it to your server in a later step.
[/callout]
[callout:tip]
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]
You'll connect to your server using **SSH**, which gives you a text-based remote control of the server.
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.
**On Mac or Linux**, open the Terminal app and type:
Don't worry if you've never done this before — you'll only need to type a few simple commands, and this guide tells you exactly what they are.
**On Mac:**
1. Open the **Terminal** app (find it in Applications > Utilities, or press `Cmd + Space` and type "Terminal")
2. Type the following command, replacing `YOUR_SERVER_IP` with the actual IP address from Step 1:
[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`).
For example, if your IP address is `203.0.113.45`, you would type: `ssh root@203.0.113.45`
**On Windows**, download and open [PuTTY](https://putty.org/) or use Windows Terminal, then connect the same way.
**On Windows:**
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.
You have two options:
- **Windows Terminal** (built into Windows 10/11): Press `Win + X`, click "Terminal", and type the same `ssh` command above
- **PuTTY** (free download): Download [PuTTY](https://www.chiark.greenend.ac.uk/~sgtatham/putty/latest.html), open it, paste your server IP in the "Host Name" field, and click "Open"
**On Linux:**
Open any terminal application and type the same `ssh` command above.
**What you'll see:**
The first time you connect, you'll get a security message. This is normal — it's your computer asking if you trust this new server. Type `yes` and press Enter.
Then you'll be asked for a password. Type the **root password** from Step 1 and press Enter.
[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
ED25519 key fingerprint is SHA256:abc123...
Are you sure you want to continue connecting (yes/no/[fingerprint])? yes
root@203.0.113.45's password:
Welcome to Ubuntu 22.04.3 LTS
root@my-server:~#
[/terminal]
You're now connected. Everything you type runs on the server, not your own computer.
When you see the `root@...:~#` prompt, you're connected. Everything you type from now on runs on your server, not on 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.
When typing a password in the terminal, **nothing appears on screen** — no dots, no asterisks, nothing at all. This is a security feature, not a bug. Just type your password and press Enter, even though it looks like nothing is happening.
[/callout]
[callout:tip]
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]
Copy and paste this single command into your terminal:
Now for the easy part. Copy and paste this single command into your terminal and press Enter:
[code:bash]
curl -fsSL https://raw.githubusercontent.com/websitebox/websitebox/main/install.sh | bash
[/code]
This does three things automatically:
[callout:tip]
**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]
1. Installs Docker (the software that runs your website)
2. Downloads WebsiteBox
3. Launches the setup wizard
This one command does everything needed to prepare your server:
You'll see output scrolling by as it installs. This takes 1-2 minutes.
1. **Installs Docker** — the software that packages and runs your website (think of it as a container system that keeps everything organized and isolated)
2. **Downloads WebsiteBox** — the project files that define your website setup
3. **Starts the setup wizard** — an interactive questionnaire to configure your site (covered in the next step)
You'll see text scrolling by as things install. This is normal — let it run. It typically takes 1-2 minutes depending on your server's speed.
[callout:warning]
If you get a "permission denied" error, try adding `sudo` in front:
**If you get a "permission denied" error**, your server may need administrator privileges. Try this version instead:
`sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/websitebox/websitebox/main/install.sh)"`
This runs the installer with administrator privileges.
`sudo` is a command that gives you administrator access. You may be asked to enter your password again.
[/callout]
[step: Complete the Setup Wizard]
The installer automatically starts a setup wizard that asks you a few questions. Here's what to expect:
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:
**Domain name** — Enter your domain without `https://` or `www`. For example: `example.com`
**1. Domain name**
Type your domain without `https://` or `www`. Just the bare domain.
- Correct: `mysite.com`
- Wrong: `https://mysite.com` or `www.mysite.com`
**Site title** — The name of your website (you can change this later). Press Enter to use the default "My Portfolio."
**2. Site title**
The name that appears at the top of your website and in browser tabs. You can change this later through WordPress, so don't stress about it.
- Press **Enter** to accept the default ("My Portfolio"), or type a custom name like `Jane's Art Gallery`
**Admin username** — Choose a username for your WordPress admin account. Don't use "admin" — pick something unique.
**3. WordPress admin username**
This is the username you'll use to log into your website's control panel. Pick something personal — the wizard won't allow "admin" for security reasons.
- Good examples: `jackie`, `jane_doe`, `myname2024`
- Not allowed: `admin`
**Admin email** — Your email address. This is used for SSL certificates and WordPress notifications.
**4. Admin email**
Your email address. WebsiteBox uses this for two things:
- Registering your free SSL certificate (the padlock icon that shows your site is secure)
- WordPress notifications (like update reminders)
**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.
**5. Admin password**
You have two options:
- **Type a password** — must be at least 12 characters. You'll be asked to type it twice to confirm.
- **Press Enter to auto-generate** — the wizard creates a strong random 20-character password for you. It will be displayed on screen and saved to a file.
**Age verification** — Choose whether visitors must confirm their age before viewing your site. Press Enter for yes, or type `n` to skip.
**6. Age verification**
WebsiteBox can require visitors to confirm their age before viewing your site. This is useful for adult content portfolios.
- Press **Enter** (or type `Y`) to enable — you'll then choose a minimum age (18-21)
- Type `n` to disable — visitors go straight to your site
**SMTP server** — Optional email sending. Press Enter to skip this for now (you can set it up later).
**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. You can configure this later.
**Backup retention** — How many days to keep backups. Press Enter to use the default (30 days).
**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.
- Press **Enter** to accept 30 days, or type a different number (1-365)
Here's an example of what the wizard looks like:
[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: ********
═══════════════════════════════════════════════════════════
WebsiteBox Setup Wizard
═══════════════════════════════════════════════════════════
Please provide the following configuration:
Domain name (e.g., example.com): myportfolio.art
Site title [My Portfolio]: Jane's Art Gallery
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.
Admin password:
Confirm 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]:
═══════════════════════════════════════════════════════════
WebsiteBox Setup Complete!
═══════════════════════════════════════════════════════════
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)
═══════════════════════════════════════════════════════════
[/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.
**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`
[/callout]
[callout:tip]
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]
Now you need to tell the internet that your domain should go to your server. This is done by setting a **DNS A record**.
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.
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)
This is done by adding a **DNS record** — specifically an **"A record"** — in your domain registrar's settings. Think of it like updating a phone book: you're telling the internet "this domain name lives at this IP address."
**How to do it:**
1. Log in to the website where you bought your domain ([Porkbun](https://porkbun.com/account/domainsSpe498), [Namecheap](https://ap.www.namecheap.com/domains/list/), [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
3. Look for an existing A record, or click **Add record** / **Add new record**
4. Fill in these values:
- **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
- **Host** or **Name:** `@` (the `@` symbol means "the root domain itself" — i.e., `yourdomain.com` without anything in front)
- **Value**, **Answer**, or **Points to:** Your server's IP address (the number from Step 1, e.g., `203.0.113.45`)
- **TTL:** Leave as "Auto" or pick the lowest number available (like 300 or 600)
5. Click **Save** or **Add 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.
**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]
**How to check if DNS is ready:**
Go back to your server terminal (reconnect with `ssh root@YOUR_SERVER_IP` if you disconnected) and type:
[code:bash]
dig yourdomain.com +short
[/code]
Replace `yourdomain.com` with your actual domain. If it shows your server's IP address, you're ready to proceed. If it shows nothing or a different IP, wait a few more minutes and try again.
[terminal]
$ dig myportfolio.art +short
203.0.113.45
[/terminal]
[callout:tip]
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]
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:
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:
[code:bash]
cd ~/websitebox
docker compose up -d
[/code]
This starts your entire website. Behind the scenes, it:
The first command (`cd ~/websitebox`) navigates to the WebsiteBox project folder. The second command (`docker compose up -d`) starts your entire website in the background. The `-d` flag means "detached" — your site keeps running even after you close the terminal.
- Starts the database
- Installs WordPress with your chosen settings
- Gets a free SSL certificate (the padlock icon in browsers)
- Configures the web server
Here's what happens automatically behind the scenes:
The first launch takes 2-3 minutes. You can watch the progress with:
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
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
[/code]
Press `Ctrl+C` to stop watching logs (this doesn't stop your site).
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.**
[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.
**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:
`docker compose restart nginx`
The SSL certificate will be obtained automatically once DNS is working.
[/callout]
[callout:tip]
After the first launch, you can always check that everything is running properly with:
`./scripts/healthcheck.sh`
You should see `[OK]` next to each service.
[/callout]
[step: Visit Your Site]
Open your browser and go to:
Open your web browser (Chrome, Firefox, Safari, etc.) and go to your domain:
- **Your website:** `https://yourdomain.com`
- **Admin dashboard:** `https://yourdomain.com/wp-admin`
Log in with the admin username and password you chose during setup.
Replace `yourdomain.com` with your actual domain name.
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.
When you visit `/wp-admin`, you'll see the WordPress login page. Enter the **admin username** and **password** you chose during the setup wizard.
If you enabled the **age verification gate**, visitors will see an age confirmation screen before any content. This is working as intended. As the site admin, you'll see it too — just confirm your age to proceed. You can customize the gate's appearance and settings later inside WordPress.
[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.
**Bookmark these two URLs:**
- `https://yourdomain.com` — your public website
- `https://yourdomain.com/wp-admin` — your admin dashboard (where you manage everything)
You'll visit `/wp-admin` frequently to add content, change settings, and manage your site.
[/callout]
[callout:info]
**You should see a padlock icon** in your browser's address bar. This means your site has a valid SSL certificate and all traffic is encrypted. If you see a security warning instead, wait a few minutes and refresh — the SSL certificate might still be processing.
[/callout]
[step: Customize Your Site]
All customization happens inside the WordPress admin dashboard. Here's where to find things:
Now that your site is live, you can customize everything through the WordPress admin dashboard — no code or terminal commands needed. Here's a tour of the most important areas:
**To change how your site looks:**
Go to **Appearance > Customize**. Here you can change colors, fonts, your logo, and the layout.
**Changing your site's appearance:**
**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).
Go to **Appearance > Customize** in the left sidebar. This opens a live preview where you can:
- Upload your **logo** and **site icon** (favicon)
- Change **colors** and **fonts**
- Adjust the **header** and **footer** layout
- Modify **page layouts** (sidebar, full-width, etc.)
**To upload images:**
Go to **Media > Add New**, or upload images directly while creating a post or page.
Every change shows a real-time preview on the right side of the screen. Click **Publish** when you're happy with the changes.
**To manage plugins:**
Go to **Plugins** in the sidebar. WebsiteBox comes with three plugins pre-installed:
**Adding content:**
- **Wordfence** — Security firewall (keeps your site safe)
- **UpdraftPlus** — Automatic backups
- **Age Gate** — Age verification (can be turned on/off under **Settings > Age Gate**)
- **Blog posts:** Go to **Posts > Add New**. Great for updates, articles, or portfolio pieces with dates.
- **Pages:** Go to **Pages > Add New**. Better for permanent content like "About Me," "Contact," or "Gallery."
- **Media uploads:** Go to **Media > Add New** to upload images, videos, or files. You can also upload directly while editing a post or page by clicking the `+` button and choosing "Image" or "Gallery."
You can install additional plugins via **Plugins > Add New**.
**Managing your pre-installed plugins:**
WebsiteBox comes with three plugins already set up:
- **[Wordfence Security](https://www.wordfence.com/)** — Protects your site from hackers and brute-force login attempts. Configure under **Wordfence** in the sidebar. The default settings are good — you don't need to change anything unless you want to.
- **[UpdraftPlus](https://updraftplus.com/)** — Creates automatic backups of your site. Configure under **Settings > UpdraftPlus Backups**. Backups are already set to save locally on your server. You can optionally add remote backup to services like [Backblaze B2](https://www.backblaze.com/b2/cloud-storage.html) or [Amazon S3](https://aws.amazon.com/s3/) for extra safety.
- **[Age Gate](https://developer.wordpress.org/plugins/age-gate/)** — The age verification screen. Configure under **Settings > Age Gate**. You can change the messaging, styling, minimum age, and which pages require verification.
**Installing additional plugins:**
Go to **Plugins > Add New** to browse thousands of free WordPress plugins. Some popular ones:
- **Contact Form 7** or **WPForms** — for adding a contact form
- **Yoast SEO** — for search engine optimization
- **WooCommerce** — if you want to sell products
- **Elementor** — a drag-and-drop page builder for more advanced layouts
[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.
The [GeneratePress](https://generatepress.com/) theme that WebsiteBox uses is lightweight, fast, and has tons of customization options built in. Explore **Appearance > Customize** thoroughly before installing additional theme plugins — you might find everything you need is already there.
[/callout]
[callout:info]
All the customization above happens through your browser in the WordPress admin. You never need to go back to the terminal for day-to-day site management.
[/callout]
[step: Keep Your Site Running]
Your website is designed to run unattended. It automatically:
One of the best things about WebsiteBox is that it takes care of itself. Once your site is up, it automatically:
- Renews your SSL certificate before it expires
- Restarts itself if the server reboots
- Backs up your data on a regular schedule
- **Renews your SSL certificate** before it expires (checked twice daily)
- **Restarts after server reboots** — if your VPS provider reboots the server for maintenance, your site comes back online automatically
- **Backs up your data** on a regular schedule via [UpdraftPlus](https://updraftplus.com/)
Here are the few maintenance tasks you may want to do occasionally:
That said, there are a few simple maintenance tasks worth doing occasionally. All of them require SSHing into your server (Step 3) and running a short command.
**Check that everything is healthy:**
**Check that everything is running smoothly:**
[code:bash]
cd ~/websitebox
./scripts/healthcheck.sh
[/code]
This checks all parts of your website and reports their status. You want to see `[OK]` next to each service:
[terminal]
═══════════════════════════════════════════════════════════
WebsiteBox Health Check
═══════════════════════════════════════════════════════════
[OK] nginx: healthy
[OK] wordpress: healthy
[OK] db: healthy
[OK] certbot: running
All services are healthy.
[/terminal]
**Update WebsiteBox** (when new versions are released):
[code:bash]
@@ -242,30 +432,40 @@ cd ~/websitebox
./scripts/update.sh
[/code]
This pulls the latest improvements, rebuilds the containers, and checks that everything is working.
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.
**Create a manual backup:**
**Create a manual backup before making big changes:**
[code:bash]
cd ~/websitebox
./scripts/backup.sh
[/code]
Backups are stored in the `websitebox-data/backups/` folder on your server.
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, 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.
**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.
[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.
**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.
[/callout]
[callout:tip]
**How often should you check in?** For most sites, checking in once a month is plenty. SSH in, run `./scripts/healthcheck.sh` to verify things are healthy, run `./scripts/update.sh` to get the latest WebsiteBox updates, and log into WordPress to apply any plugin/theme updates. The whole process takes about 5 minutes.
[/callout]
[step: Troubleshooting]
If something goes wrong, here are the most common fixes:
If something isn't working, don't panic. Here are the most common issues and exactly how to fix them. For all of these, you'll need to SSH into your server (same as Step 3) first.
**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:
**Your site shows a "Setting up SSL..." page:**
This means the SSL certificate hasn't been issued yet, usually because DNS isn't pointing to your server. To fix:
1. Go back to your domain registrar and double-check the A record points to the correct IP address (Step 6)
2. Wait for DNS propagation — try `dig yourdomain.com +short` to check
3. Once DNS is correct, tell the web server to retry:
[code:bash]
cd ~/websitebox
@@ -273,31 +473,49 @@ 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:
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:
[code:bash]
cd ~/websitebox
docker compose ps
[/code]
**You forgot your admin password:**
You can reset it from the server:
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
[/code]
**You forgot your WordPress admin password:**
No problem — you can reset it from the server. Replace `YOUR_USERNAME` with your actual admin username and `NEW_PASSWORD` with your new desired password:
[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.
For example, if your username is `janedoe` and you want the password `MyNewSecurePass123`:
**"Permission denied" when running docker commands:**
Run this, then log out and back in:
[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
[/code]
**"Permission denied" when running Docker commands:**
This means your user account doesn't have permission to use Docker. Fix it by running:
[code:bash]
sudo usermod -aG docker $USER
[/code]
**Containers won't start after a server reboot:**
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.
**Your site is down after a server reboot:**
Docker should restart automatically, but if it doesn't:
[code:bash]
sudo systemctl start docker
@@ -305,15 +523,37 @@ cd ~/websitebox
docker compose up -d
[/code]
**View detailed logs for a specific service:**
The first command starts Docker itself, and the second starts your website containers.
**Something else is wrong and you need more details:**
View the live logs for each part of your website to see what's happening:
[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.
Replace `nginx` with `wordpress` or `db` to see logs for those services instead. Press `Ctrl+C` to stop watching.
**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]
cd ~/websitebox
docker compose down
rm -rf websitebox-data/
./setup.sh
docker compose up -d
[/code]
This keeps your server intact and re-runs the setup wizard from scratch. You'll need to re-enter your configuration and set up your content 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.
[/callout]
[callout:tip]
If you're stuck and the solutions above don't help, check the full [Troubleshooting guide](docs/TROUBLESHOOTING.md) in the WebsiteBox repository for more detailed solutions covering upload limits, database connections, SSL renewal, and more.
[/callout]