websitebox/guide.md

title, summary, tags, difficulty, time, prerequisites

title	summary	tags	difficulty	time	prerequisites
Deploy Your Own Website with WebsiteBox	Go from zero to a live, SSL-secured WordPress website on your own server. No coding or technical experience required.	WordPress, Docker, Self-Hosting, VPS	beginner	45 minutes	A credit card for VPS hosting ($3.50-6/month), A domain name ($1-12/year)

[step: Get a Server]

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.

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.

Recommended providers (click to sign up):

• BuyVM — $3.50/mo, most affordable, great for all content types, includes free DDoS protection
• Vultr — $6/mo, very beginner-friendly dashboard, widely used
• OVHcloud — $5.50/mo, European-based, good for EU audiences

[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]

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 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]

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.

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 — Low prices, very simple interface, great for beginners
• Namecheap — Large selection, frequent sales
• Cloudflare 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. 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]

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.

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]

For example, if your IP address is 203.0.113.45, you would type: ssh root@203.0.113.45

On Windows:

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, 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. 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]

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, 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]

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]

[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]

This one command does everything needed to prepare your server:

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, your server may need administrator privileges. Try this version instead:

sudo bash -c "$(curl -fsSL https://raw.githubusercontent.com/websitebox/websitebox/main/install.sh)"

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 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:

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

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

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

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)

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.

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

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.

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] ═══════════════════════════════════════════════════════════ 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]

[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 [/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]

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.

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, Namecheap, Cloudflare, 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
   • 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] 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 — type in your domain and see if servers around the world are returning your IP address. [/callout]

[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:

[code:bash] cd ~/websitebox docker compose up -d [/code]

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.

Here's what happens automatically behind the scenes:

1. Database starts — MariaDB (a database server) starts up to store your website's content
2. WordPress installs — WordPress is set up with your chosen title, username, and plugins
3. SSL certificate acquired — A free security certificate from Let's Encrypt is obtained so your site gets the padlock icon in browsers
4. Web server configured — Nginx (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]

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 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 web browser (Chrome, Firefox, Safari, etc.) and go to your domain:

• Your website: https://yourdomain.com
• Admin dashboard: https://yourdomain.com/wp-admin

Replace yourdomain.com with your actual domain name.

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 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]

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:

Changing your site's appearance:

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.)

Every change shows a real-time preview on the right side of the screen. Click Publish when you're happy with the changes.

Adding content:

• 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."

Managing your pre-installed plugins:

WebsiteBox comes with three plugins already set up:

• Wordfence Security — 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 — 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 or Amazon S3 for extra safety.
• 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] The GeneratePress 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]

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 (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

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 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] 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.

Create a manual backup before making big changes:

[code:bash] 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.

[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. [/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 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 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 docker compose 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:

[code:bash] cd ~/websitebox docker compose 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 [/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]

For example, if your username is janedoe and you want the password 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 [/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]

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 cd ~/websitebox docker compose up -d [/code]

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 [/code]

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 in the WebsiteBox repository for more detailed solutions covering upload limits, database connections, SSL renewal, and more. [/callout]