It’s often useful to test pages locally before deploying, as it can save time and be helpful for testing quick changes/debugging. In this blog we’ll learn how to deploy fastpages locally using Docker.

Overview of steps

  1. Download Docker desktop
  2. (For Windows) Set up Docker with WSL
  3. Run make server in repo directory
  4. Click in terminal or type localhost link show (ex. http://127.0.0.1:4000/{repo name}) to view your Fastpages Blog site.

1. Installation

Docker is a lightweight method to build, deploy, run, update and manage containers. Download Docker desktop from following links:

Windows: https://docs.docker.com/desktop/install/windows-install/ Mac: https://docs.docker.com/desktop/install/mac-install/.

Now, each time you want to make server, you need to start Docker desktop or make sure it running. Make sure you do this before building locally!

2. (For Windows) Set up Docker with WSL

For Windows, to set up Docker with WSL use https://docs.docker.com/desktop/windows/wsl/.

(Optional) Download Docker extension in VSCode

VSCode has an extension too make it easier to manage docker containers and images directly in your IDE. To download, go to the Extensions tab of VSCode (left bar, or Ctrl+Shift+X), search “Docker” and download the extension from Microsoft. You should now see a docker icon on the left bar, which you can click on to see your Docker connections.

3. Using VSCode Terminal, run: make server

In the local repository, make sure you are cd’ed to the base/root directory (i.e. where the Makefile is). For Ellen that was the ap-csa-fastpages directory as pictured. For Mr M, cd ~/vscode/APCSA sets him in his APCSA repository, here the make server command will work if Docker is running.

image

The Makefile contains common aliased commands for building and serving your fastpages locally. If you look inside the file or run make in terminal, you can see what docker commands it can run.

image

Specifically, we are interested in the make server command, which will build the container the first time and start the Jekyll server. If you remember from APCSP, Jekyll is what powers Github pages behind the scenes. You can build your GitHub Pages site locally using Jekyll to preview and test changes to your site.

Special steps for Windows

The first time, you might get this issue:

image

If that’s the case, make sure this setting is toggled on in Docker desktop settings:

image

It should ask you to reload and if you run the command again it should work now.

4. View blog

After running, look for link to run Server. For me, this was http://127.0.0.1:4000/{repo name}:

Server address: http://127.0.0.1:4000/

Server running… press ctrl-c to stop.

Shift-click server address to launch in Browser.

Leave the server running!!!

Make edits in VSCode and save the file. On each save, watch terminal in VSCode to see updates and regeneration of WebSite.

Refresh or click to Web page of change and you will see updates almost instantly. Refer to VSCode terminal to see any error encountered when running your server. As indicated ctrl-c will stop the server, however, I have left it running for hours of edits, testing, and commits to GitHub.

Alert, when you are satisfied with local changes… you must ✔️Commit and Sync to GitHub. The local server is used to preview and test change prior to Sync. Only after Sync, will others be able to see your changes.

image

Add to .gitignore

A side effect of building locally is that it converts all the .ipynb and .docx files to .md. This means that some files will have duplicates after building – one in .ipynb or .docx, another in .md form.

To avoid duplicates masters when pushing to github, add the md generated files from to the .gitignore. This can be done by right clicking md file when preparing commits. Below is a sample .gitignore. The 1st three lines should be universal to all fastpages projects, the other files are specific to your project.

# Ignore from local build
settings.ini
Gemfile.lock
images/copied_from_nb/
_posts/2022-08-15-AP-anatomy.md
_posts/2022-08-22-HM-anthony_and_sahil.md
_posts/2022-08-22-TT-darkmode.md
_posts/2022-08-22-AP-primitives.md
_posts/2022-08-22-TT-bash_tutorial.md
_posts/2022-08-29-AP-using_java_objects.md
_posts/2022-09-05-AP-boolean_ifs.md
_posts/2022-09-19-TT-js_tutorial.md
_posts/2022-09-26-TT-rapidapi.md

Resources

https://github.com/fastai/fastpages/blob/master/_fastpages_docs/DEVELOPMENT.md