Documentation Server Setup & Updates

This guide covers the full setup of the private Docusaurus documentation site on an Amazon Linux 2023 (AL2023) EC2 instance, protected by HTTP Basic Auth via Apache. It also documents the one-liner update workflow used whenever new content is pushed to GitHub.

---

Prerequisites

• An Amazon Linux 2023 EC2 instance with a public IP address.
• SSH access as ec2-user.
• The Rhino-Group/scottsdale-documentation GitHub repository.

---

Phase 1: Install the Essentials

Update the system and install Apache, Node.js, and Git.

# 1. Update the system
sudo dnf update -y

# 2. Install Apache, Node.js, and Git
sudo dnf install -y httpd nodejs git

# 3. Start Apache and enable it to run at boot
sudo systemctl start httpd
sudo systemctl enable httpd

---

Phase 2: Install GitHub CLI & Clone the Repository

AL2023 does not include gh in its default repositories, so the official GitHub CLI repo must be added first.

# 1. Add the GitHub CLI repository
sudo dnf config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo

# 2. Install gh
sudo dnf install -y gh

# 3. Authenticate with GitHub
gh auth login
# Follow the prompts: select GitHub.com, choose SSH or HTTPS,
# and authenticate via the browser/device-code method.

# 4. Clone the repository to the home directory
cd ~
gh repo clone Rhino-Group/scottsdale-documentation

---

Phase 3: Install Typesense

Typesense runs on the same instance as the documentation site. It provides the full-text search experience in the Docusaurus UI.

Step 1 — Install Typesense

# 1. Add the Typesense repo and install
sudo rpm --import https://dl.typesense.org/rpm/pubkey.gpg
sudo tee /etc/yum.repos.d/typesense.repo <<EOF
[typesense]
name=Typesense
baseurl=https://dl.typesense.org/rpm/stable/\$basearch
enabled=1
gpgcheck=1
gpgkey=https://dl.typesense.org/rpm/pubkey.gpg
EOF

sudo dnf install -y typesense-server

Step 2 — Configure Typesense

sudo nano /etc/typesense/typesense-server.ini

Set the following values:

[server]
api-key = scottsdale-docs-admin
data-dir = /var/lib/typesense
log-dir = /var/log/typesense
listen-port = 8108
enable-cors = true

Save and exit: Ctrl+O → Enter → Ctrl+X.

Step 3 — Create a search-only API key

The scottsdale-docs-admin key is used only server-side by the scraper. Create a read-only key that is safe to embed in the browser bundle:

curl -X POST 'http://localhost:8108/keys' \
  -H 'X-TYPESENSE-API-KEY: scottsdale-docs-admin' \
  -H 'Content-Type: application/json' \
  -d '{"description":"Search-only key for Docusaurus","actions":["documents:search"],"collections":["scottsdale-docs"]}'

Copy the value from the response — this is the search-only key. Update TYPESENSE_SEARCH_API_KEY in docusaurus.config.ts:

apiKey: '<paste-search-only-key-here>',

Step 4 — Start and enable Typesense

sudo systemctl start typesense-server
sudo systemctl enable typesense-server

# Verify it is running
curl http://localhost:8108/health
# Expected: {"ok":true}

Step 5 — Install Docker (for the scraper)

The Typesense scraper runs as a Docker container to crawl the built site and populate the search index.

sudo dnf install -y docker
sudo systemctl start docker
sudo systemctl enable docker
sudo usermod -aG docker ec2-user
# Log out and back in for the group change to take effect.

Step 6 — Run the initial index

cd ~/scottsdale-documentation
docker run --rm --net=host \
  -e "TYPESENSE_API_KEY=scottsdale-docs-admin" \
  -e "CONFIG=$(cat typesense-scraper-config.json)" \
  typesense/docsearch-scraper

note

The scraper crawls http://localhost/ so it must be run after the site has been deployed to /var/www/html. The update-docs.sh script automatically re-runs this after every deployment.

---

Phase 4: Build the Docusaurus Site

cd ~/scottsdale-documentation

# 1. Install dependencies
npm install

# 2. Build the static site
npm run build

Swap Memory

If npm run build hangs or crashes on a small instance type (e.g., t3.micro), the instance likely needs swap memory. Add at least 1 GB of swap before retrying.

sudo dd if=/dev/zero of=/swapfile bs=128M count=8
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

---

Phase 5: Configure HTTP Basic Authentication

Lock the site behind a login prompt before deploying any files.

Step 1 — Create the password file

This creates a user named admin. You will be prompted to set a password.

sudo htpasswd -c /etc/httpd/.htpasswd admin

Step 2 — Configure Apache

sudo nano /etc/httpd/conf/httpd.conf

Find the <Directory "/var/www/html"> block and update it to match the following. Also add the <Location /typesense> block above it — this exempts the Typesense proxy path from Basic Auth so the browser-side search can reach Typesense without credentials:

# --- Typesense proxy (must come before the Directory auth block) ---
# Exempt /typesense from Basic Auth so the Docusaurus search UI can reach it.
<Location /typesense>
    AuthType None
    Require all granted

    ProxyPass        http://localhost:8108
    ProxyPassReverse http://localhost:8108
</Location>
# ------------------------------------------------------------------

<Directory "/var/www/html">
    Options Indexes FollowSymLinks
    AllowOverride None

    # --- Authentication ---
    AuthType Basic
    AuthName "Private Documentation - Please Login"
    AuthUserFile /etc/httpd/.htpasswd
    Require valid-user
    # ----------------------
</Directory>

Also ensure mod_proxy and mod_proxy_http are loaded — add these lines near the top of httpd.conf if not already present:

LoadModule proxy_module modules/mod_proxy.so
LoadModule proxy_http_module modules/mod_proxy_http.so

Save and exit: Ctrl+O → Enter → Ctrl+X.

After saving, restart Apache:

sudo systemctl restart httpd

---

Phase 6: Deploy the Built Site

# 1. Give ec2-user ownership of the web root
sudo chown -R ec2-user:ec2-user /var/www/html

# 2. Remove the default Apache test page
rm -rf /var/www/html/*

# 3. Copy the Docusaurus build output to the web root
cp -R ~/scottsdale-documentation/build/* /var/www/html/

# 4. Restart Apache to apply the authentication configuration
sudo systemctl restart httpd

---

Phase 7: Verify

1. Open the EC2 Dashboard and copy the instance's Public IPv4 address.
2. Paste it into a browser.
3. A login dialog should appear. Enter admin and the password set in Phase 5.
4. Your Docusaurus documentation site should load successfully.
5. Use the search bar (top-right) to confirm Typesense search is returning results.

---

Updating the Documentation

Whenever new content is merged into master on GitHub, run the included update script to pull, rebuild, and deploy in one step.

Using the update script (recommended)

The script lives at scripts/update-docs.sh in the repository root. On first use, make it executable:

chmod +x ~/scottsdale-documentation/scripts/update-docs.sh

Then run it any time you want to deploy the latest content:

~/scottsdale-documentation/scripts/update-docs.sh

The script logs every step with timestamps to ~/update-docs.log and exits immediately if any step fails, preventing a broken build from being deployed.

Adding the script to your PATH

To run update-docs from any directory without specifying the full path, add the scripts/ directory to your shell's PATH in ~/.bashrc:

echo 'export PATH="$HOME/scottsdale-documentation/scripts:$PATH"' >> ~/.bashrc
source ~/.bashrc

You can then invoke it from anywhere as:

update-docs.sh

To confirm it is on your PATH:

which update-docs.sh

Manual one-liner (alternative)

cd ~/scottsdale-documentation && git pull && npm install && npm run build && cp -R build/* /var/www/html/

Step	What it does
git pull	Fetches and merges the latest commits from master
npm install	Installs any new or updated dependencies
npm run build	Compiles Docusaurus into a static site in ./build
cp -R build/* /var/www/html/	Deploys the new build to the Apache web root

---

Managing Basic Auth Users

Task	Command
Add a new user	sudo htpasswd /etc/httpd/.htpasswd <username>
Change a user's password	sudo htpasswd /etc/httpd/.htpasswd <username>
Remove a user	sudo htpasswd -D /etc/httpd/.htpasswd <username>
List all users	sudo cat /etc/httpd/.htpasswd

After any changes to .htpasswd, restart Apache:

sudo systemctl restart httpd

---

Next Steps

• Set up a custom domain and SSL/TLS certificate using Let's Encrypt / Certbot.
• Automate deployments with a cron job or a GitHub Actions webhook to remove the need to SSH in manually.