1. Create a VM

Open VMware Workstation 17 Pro (17.5.2 build-23775571) and click File > New Virtual Machine… (Ctrl+N).

[!NOTE]

Ran this on Microsoft Windows 11 Pro Version 10.0.26100 Build 26100 (from System Information)
On the Welcome Screen, leave the default: Typical. Click Next >.
On the Guest Operating System Installation screen, set Installer disc image file (iso) to your ubuntu-24.04.3-desktop-amd64.iso. Click Next >.
On the Easy Install Information screen, set Full Name to Demo User, User name to demo-user, Password and Confirm to (your password). Click Next >.
On the Name the Virtual Machine screen, set Virtual machine name to Ubuntu_64-bit. Click Browse… Click Make New Folder. Create sitedev_24.04.3. Click Next >.
On the Specify Disk Capacity screen, leave defaults: Maximum disk size (GB): 20 GB, Split virtual disk into multiple files. Click Next >.
On the Ready to Create Virtual Machine screen, leave defaults. Click Finish.

The VM should start, and the installer should come up.

2. Install Ubuntu

Click on the disk icon.
Use defaults till the Create your account screen.
Set Your name to Demo User, Your computer’s name to demo, Your username to demo-user, a password. Leave other defaults. Click Next.
Use defaults for all remaining screens and start the install.
On the Installation complete screen, you can do 1 of 2 things: 1) click the Restart now button or 2) close the installer, shutdown, remove the ISO from the VM, and restart. You should see a Welcome to Ubuntu 24.04.3 LTS screen, click next. Skip Ubuntu Pro. Select Don’t share data and click Finish.

Enable VM to Host Shared Folders and Copy/Paste (Optional)

After booting, open a terminal and run:

sudo apt-get install open-vm-tools open-vm-tools-desktop

Power off and restart.

[!WARNING]

Running sudo systemctl restart vmtoolsd.service instead of rebooting doesn’t work reliably for me.

Change Screen Resolution (Optional)

After booting, change the screen resolution. Right-click the desktop. Click Display settings. Choose a new setting. On Keep settings popup, click Ok.

3. Get git and gh

sudo apt-get install git gh

Configure git

git config --global user.email "[email protected]"
git config --global user.name "Arthur Dent"

In Ubuntu, open Firefox and go to github.com. Click Sign in in the upper right or Sign up to create and account.

Run gh auth login and use defaults.

Get other packages (Optional)

curl and Vim

sudo apt-get install curl vim

Typora

[!NOTE]

From https://typora.io/#linux

# add Typora's key

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://downloads.typora.io/typora.gpg | sudo tee /etc/apt/keyrings/typora.gpg > /dev/null
# add Typora's repository securely
echo "deb [signed-by=/etc/apt/keyrings/typora.gpg] https://downloads.typora.io/linux ./" | sudo tee /etc/apt/sources.list.d/typora.list
sudo apt update
# install typora
sudo apt install typora

6. Install and Configure Development Tools: ruby, jekyll, bundler

[!NOTE]

Adapted from instructions listed on:

https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/testing-your-github-pages-site-locally-with-jekyllhttps://jekyllrb.com/docs/installation/ubuntu/

Install Ruby and other prerequisites

sudo apt-get install ruby-full build-essential zlib1g-dev

Set up a gem installation directory for your user account

echo '# Install Ruby Gems to ~/gems' >> ~/.bashrc
echo 'export GEM_HOME="$HOME/gems"' >> ~/.bashrc
echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

Install Jekyll and Bundler

gem install jekyll bundler

[!NOTE]

The last 3 lines you should see:

...
Installing ri documentation for bundler-2.7.2
Done installing documentation for bundler after 0 seconds
30 gems installed

Clone site into home dir:

cd ~
git clone https://github.com/centennialsoftwaresolutions/centennialsoftwaresolutions.github.io.git
cd ~/centennialsoftwaresolutions.github.io

Check Gemfile

   cd ~/centennialsoftwaresolutions.github.io
   cat Gemfile

You should see:

   source "https://rubygems.org"

   gem "github-pages", group: :jekyll_plugins
   gem "webrick", "~> 1.8"
   gem "jekyll-sitemap"

Keep gems in the project
```
bundle config set path 'vendor/bundle'
```
Install gems
```
bundle install
```

7. Run and Test

Serve pages:

bundle exec jekyll serve

You should see:

Configuration file: /home/demo-user/centennialsoftwaresolutions.github.io/_config.yml
To use retry middleware with Faraday v2.0+, install `faraday-retry` gem
            Source: /home/demo-user/centennialsoftwaresolutions.github.io
       Destination: /home/demo-user/centennialsoftwaresolutions.github.io/_site
 Incremental build: disabled. Enable with --incremental
      Generating... 
       Jekyll Feed: Generating feed for posts

Then wait a bit. After just over a minute on my machine, I see:

                    done in 73.598 seconds.
 Auto-regeneration: enabled for '/home/demo-user/centennialsoftwaresolutions.github.io'
    Server address: http://127.0.0.1:4000/
  Server running... press ctrl-c to stop.

Open a browser window to http://127.0.0.1:4000/ and you should see the site.

Serve & rerun with each save:
```
bundle exec jekyll serve --incremental
```

Errors You May See

`bundle install` error

[DEPRECATED] This Gemfile does not include an explicit global source. ...
Could not find gem 'github-pages' in locally installed gems.

Cause: Your Gemfile is missing a global source or the correct gems.

Fix: Make sure your Gemfile looks like this:

source "https://rubygems.org"

gem "github-pages", group: :jekyll_plugins
gem "webrick", "~> 1.8"

Then run:

bundle install

`bundle exec jekyll serve` error

Could not find gem 'github-pages' in locally installed gems.
Run `bundle install` to install missing gems.

Cause: Gems have not been installed yet.

Fix: Run:

cd ~/post/
bundle install

…to install everything from your Gemfile, then retry:

bundle exec jekyll serve