Step by step instructions to get al-folio up and running on your local machine using Docker and Visual Studio Code (VS Code)

Built with Fedora 42

Install Docker Desktop

al-folio supports Development Containers. For example, when you open the repository with Visual Studio Code (VSCode), it prompts you to install the necessary extension and automatically install everything necessary.

But the local setup is not as easy as the repository creators claim. For this reason I decided to create these instructions to be used whenever we reinstall the operating system (OS), or update Docker Desktop or VS Code.

1 - The kvm module should load automatically if the host has virtualization support. Check if the KVM modules are enabled.

lsmod | grep kvm

kvm_amd           249856  0
kvm              1482752  1 kvm_amd
irqbypass          12288  1 kvm

If this command lists kvm_amd or kvm_intel, KVM is configured correctly.

2 - Install Docker Desktop repository.

sudo dnf-3 config-manager --add-repo https://download.docker.com/linux/fedora/docker-ce.repo

3 - Download the latest version of RPM from https://docs.docker.com/desktop/release-notes/

4 - Install the package.

sudo dnf install ./docker-desktop-x86_64.rpm

5 - Launch Docker Desktop.

systemctl --user start docker-desktop

6 - The Docker Subscription Service Agreement displays. Select Accept to continue. Docker Desktop starts after you accept the terms. Do not proceed to Sign. Press “Skip” and “Skip”.

7 - Enable Docker Desktop to start on sign in on Fedora

systemctl --user enable docker-desktop

Note: Upgrade Docker Desktop

Once a new version for Docker Desktop is released, the Docker UI shows a notification. You need to first remove the previous version and then download the new package each time you want to upgrade Docker Desktop. Run:

sudo dnf remove docker-desktop

sudo dnf install ./docker-desktop-x86_64.rpm

Install VS Code

8 – Install the key and yum repository by running the following script:

sudo rpm --import https://packages.microsoft.com/keys/microsoft.asc

echo -e "[code]\nname=Visual Studio Code\nbaseurl=https://packages.microsoft.com/yumrepos/vscode\nenabled=1\nautorefresh=1\ntype=rpm-md\ngpgcheck=1\ngpgkey=https://packages.microsoft.com/keys/microsoft.asc" | sudo tee /etc/yum.repos.d/vscode.repo > /dev/null

9 - Then update the package cache and install the package using dnf.

dnf check-update

sudo dnf install code

Working with GitHub in VS Code

It is assumed that you already have Git installed locally on your system and the repository on GitHub.

10 – Start VS Code.

11 - Clone the repository.
On the Welcome page you click on ‘Clone Git Repository…”
A window appears with the warning: “The ‘GitHub’ Extension wants to sign using GitHub”. Allow.
A tab automatically opens in Firefox to “Sign in to GitHub”. Fill in the fields.
In VS Code select the repository and choose a folder to clone.
Select “Open” to open the cloned repository.
A warning window opens: “Do you trust the authors of the files in this folder? Select the option “Trust the authors of all files in the parent folder” and click “Yes, I trust the authors”.
A window appears for installing ‘Dev Containers’. Do not install for now. Close VS Code.

12 - Caching your GitHub credentials in Git
Install the GitHub CLI (gh) and run it to automatically store your credentials on GitHub. You can then choose HTTPS as your preferred protocol for Git operations, and answer “yes” to the prompt that will ask if you would like to authenticate to Git with your GitHub credentials.

sudo dnf install gh

gh auth login

Select the following answers to the following questions:

Where do you use GitHub? GitHub.com
What is your preferred protocol for Git operations on this host? HTTPS
Authenticate Git with your GitHub credentials? Y(es)
How would you like to authenticate GitHub CLI? Login with a web browser
!First copy your one-time code: XXXX-XXXX (It is a code with letters and numbers that will be used in the browser in the next step, right after authenticating.) Press Enter to open https://github.com/login/device in your browser… ✓ Authentication complete.

Git Configuration

13 - Enter the local repository folder.

cd username.github.io

git config --global user.name "My Name"

git config --global user.email me@example.com

14 - Start VS Code.
Wait a few seconds for the “Do you want to install the recommended ‘Dev Containers’ extension…” window to appear again. Click ‘Install’.
A new window will appear. Click ‘Reopen in Container’.
During ‘Connecting to Dev Container’ an error message may appear. Click ‘Retry’.