DEV Community: Erika Heidi

Working with Git Branches and Pull Requests

Erika Heidi — Tue, 19 Nov 2024 17:48:29 +0000

Git Branches Overview

Git branches are an essential feature of the Git version control system. They allow developers to work on different versions of a project simultaneously without affecting the main branch. Branches also enable multiple developers to work on the same project without interfering with each other's work. By creating a branch for each task or feature, developers can work independently and merge their changes back into the main branch when they're ready. Branches also facilitate tracking changes and reverting to previous versions of the code if necessary.

So far, we have only worked on the main branch. It is a convention to use main as the default branch where the most up-to-date version of a project can be found. Active development typically occurs in separate branches that are later on merged into main. Software releases are also typically based on the main branch, although it is possible to maintain several branches with different versions of a software.

The Pull Request Workflow

In the previous chapter of this series, you cloned a remote Git repository, made changes, and pushed the changes back directly into the main branch. In a collaborative workflow, you would be making changes to a separate branch (for example, readme-updates), then push this branch to the remote repository, and then open a pull request (PR for short) to request that your readme-updates branch be pulled or merged into main. Another collaborator would then be able to review your pull request before the changes are merged. GitHub offers several tools and even AI assistance for pull request reviews, which can be very helpful when working with teams.

If you are just starting and working solo on a project, you might wonder why you should care about pull requests at all. Here's why practicing this workflow is advantageous for beginners:

Better understanding of how branches and merging work
Preparation for contributing code to existing projects
Familiarization with the process of reviewing and approving pull requests

Undoubtedly, GitHub stands as the preeminent code platform in the market, making it imperative for you to acquaint yourself with its workflows and diverse features. It’s very likely that you’ll need to use this platform eventually, either for work or for academic purposes. So starting early might give you an advantage that others don’t have.

Creating your First Pull Request

We’ll now repeat what we did in the previous article, where we pushed some changes to your profile README directly from your local machine. This time around, however, we’ll work on a separate branch, and push this branch over to upstream. Then, you’ll open a pull request to learn how that works.

If for some reason you don’t have the project on your local machine, start by cloning the repo. You can obtain the SSH URL for the repository in its GitHub landing page by clicking on the green “Code” button. The URL follows this pattern: git@github.com:username/repo.git. Once you grab that URL, run git clone from your home directory and then cd into the newly created folder:

git clone git@github.com:boredcatmom/boredcatmom.git
cd boredcatmom

If you’ve followed along with the previous guides, you should have a single README.md file in your repository. You’ll now create a new branch based off of main before you start making changes to your file. To do so, run the following command:

git checkout -b readme-updates

Switched to a new branch 'readme-updates'

The git checkout command is used to switch between branches. To create a new branch, use the -b parameter. If the branch already exists, use just git checkout branch-name to make the switch.

Now make some changes to the file. When you’re finished, proceed with the workflow of adding files to staging and committing changes:

git add README.md
git commit -m "updted"

[readme-updates 8c8f620] updted
 1 file changed, 1 insertion(+), 1 deletion(-)

Now, push the changes to upstream. Instead of pushing to main, thou, you’ll be pushing it to a branch with the same name as your local branch:

git push origin readme-updates

You’ll get output similar to this:

Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 8 threads
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 1.31 KiB | 1.31 MiB/s, done.
Total 3 (delta 1), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
remote:
remote: Create a pull request for 'readme-updates' on GitHub by visiting:
remote:     https://github.com/boredcatmom/boredcatmom/pull/new/readme-updates
remote:
To github.com:boredcatmom/boredcatmom.git
 * [new branch]     readme-updates -> readme-updates

As you can notice from the output, there’s a special URL you can access to create a pull request based on this branch. You can also simply access your repository page on GitHub and a prominent dialog will appear asking if you want to create a pull request based on the new branch that was just pushed:

Click on the “Compare & pull request” button to open the pull request form. You’ll see a page similar to this:

The select box on the top of the screen lets you select the source branch and the target branch for the pull request. Typically you won’t need to change this. The PR form uses your commit message as title, and has a text area for you to describe the changes you are proposing and adding any relevant information to help test and review the pull request.

The bottom area of the pull request form shows a diff view of what has changed in this branch when compared to main. Red-highlighted lines are removed lines, and green-highlighted lines are new additions to the file.

Click on the green “Create pull request” button to create the PR. You’ll be redirected to the newly created pull request page:

Congratulations! You have created your first pull request.

Reviewing a Pull Request

The process of reviewing a pull request varies greatly depending on the project, company, and/or team. In general, you’ll be looking at the “Files changed” tab of the pull request page, where you’ll be able to find all changed files with a rich diff that enables you to quickly visualize what was changed in that PR.

The GitHub interface allows for directly making comments and suggestions in the “Files changed” tab. Click on the blue + sign that shows up on each line (when you hover your mouse over that little space between the line number and the beginning of the line) to open the comments / suggestions form:

To approve or request changes to a PR, click on the green “Review changes” button on the top right to access the PR approval form. Because PR authors cannot approve their own pull requests, you won’t be able to use the form to review your own PR, as you can merge it directly to main when you’re ready.

Merging a Pull Request

When the PR is good to merge and there are no issues such as conflicting changes, you can click on the green “Merge pull request” button, and GitHub will merge the pull request into your main branch.

Updating your Local Repository

When pull requests are merged through the GitHub interface, a new commit is created in the main branch carrying the changes that were merged. Your local copy of the repository will be outdated, with the main branch still pointing to a previous commit.

Start by switching to the main branch:

git checkout main

To pull the changes and update your local main branch, run:

git pull origin main

This will make sure any additional changes made from other authors or directly from the GitHub interface are pulled into your local repository. You should get output similar to this:

remote: Enumerating objects: 1, done.
remote: Counting objects: 100% (1/1), done.
remote: Total 1 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
Unpacking objects: 100% (1/1), 885 bytes | 885.00 KiB/s, done.
From github.com:boredcatmom/boredcatmom
 * branch           main    -> FETCH_HEAD
   26edb28..d42543d  main       -> origin/main
Updating 26edb28..d42543d
Fast-forward
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

If you run git log now, you should be able to confirm that your local main branch now points to the commit that merged the pull request from the readme-updates branch:

commit d42543de4d1ed7ec2c96c35500986ac882b94f3d (HEAD -> main, origin/main, origin/HEAD)
Merge: 26edb28 8c8f620
Author: boredcatmom <boredcatmom@hotmail.com>
Date:   Tue Nov 19 15:20:33 2024 +0100

    Merge pull request #1 from boredcatmom/readme-updates

    Updated

It’s important to keep your main branch always up-to-date with your upstream, in order to avoid merge conflicts and other issues.

Sending PRs to Other People’s Projects

When working on other people's projects on platforms like GitHub, you'll often need to fork the repository to your account before you can make changes. This is because you don't have direct write access to the original repository.

Forking a repository creates a copy of the original repository in your account. You can then make changes to your forked repository without affecting the original. Once you're finished making changes, you can submit a pull request to the original repository. This will notify the original repository owner that you have changes that you'd like them to consider merging into their repository.

For more information on forking repositories, check the official GitHub documentation.

Appendix: Merge Conflicts and Common Mistakes

Despite its seemingly simple commands, Git can be quite tricky at times. Its complexity stems from the intricate web of branches, commits, and merges that it manages. Let’s review common issues in this short appendix.

Merge Conflicts

A merge conflict occurs when you try to merge two branches that have conflicting changes to the same file. This can happen when multiple developers are working on the same file at the same time and make changes that overlap. Although slightly annoying, merge conflicts are a very common occurence in Git world, so it’s nothing to be scared of.

When a merge conflict occurs, Git will stop the merge process and display a message indicating which files have conflicts. You will need to resolve the conflicts manually before you can continue with the merge. Merge conflicts also prevent maintainers from using the GitHub interface to merge pull requests, requiring manual intervention.

Git adds special markers on conflicting files so that you can identify the differences and choose which version you’ll keep. After you’re finished with the changes, you can continue with the merge process.

Please refer to the official GitHub Documentation for detailed resources to assist with merge conflicts.

Common mistakes when working with Git

We all have done it before, and we may still do it again sometimes! These common mistakes can cause issues such as merge conflicts, data inconsistency, or increased security risks.

Pushing to the wrong branch: if you try to push your local branch to a remote branch that doesn’t match your history, you’ll likely get a write error message, or you may end up with several merge conflicts.
Forgetting to add files to the staging area: you can only create a commit if you have files in staging. Also, be mindful of what you’re adding to the repository. You can use a .gitignore file to add files that should be ignored.
Accidentally deleting or overwriting files: it may happen that you delete a local file by mistake and accidentally commit that change to the repo. That’s why it’s important to pay attention to what’s in stage before creating your commits.
Accidentally committing files with sensitive information: this can pose a serious security risk to a project or user. Files with sensitive information such as passwords and tokens should never be committed to the repository. Add any files with sensitive data to your .gitignore.
Pushing local changes without pulling remote changes first: the most likely outcome of pushing local changes without pulling updates first is a merge conflict. Always remember to update your branches before pushing to origin.
Forgetting to push changes to the remote repository: sometimes we just forget to hit that final push and send the changes to the repository. Not a big deal, but a very common thing to happen 🙂

Conclusion

In this guide, you learned about branches and the mighty Pull Request workflow. Hooray! You have now the basic tools to start building on GitHub, and to start contributing to open source projects, if that’s something you’re interested in. Coding can definitely be more fun with friends, and luckily for us, GitHub is an excellent platform to build projects together just like that.

With that, our Git and GitHub Crash Course comes to an end. Here are some resources you may refer to if you want to learn more about Git and GitHub:

Working with GitHub Repositories

Erika Heidi — Tue, 19 Nov 2024 17:47:46 +0000

In a previous part of this series, you saw how to create a new GitHub account and how to customize your profile by committing a README file into a special repository. We did all this through GitHub’s web interface. In this guide, you’ll learn how to work with GitHub repositories by pulling this special repository to your local machine, making changes to your README, and pushing the changes back to GitHub.

Creating a New SSH Key

For increased security when working with remote Git repositories, it is recommended to set up an SSH key for communicating with GitHub. If you already have an SSH key set up for your current system user, you can skip to the next step.

You can create a new SSH key by running the following command on your terminal, replacing “your_email@example.com” with your actual email address:

ssh-keygen -t ed25519 -C "your_email@example.com"

You will be prompted to provide the location to save your key, and a passphrase. You can use the default location ~/.ssh/id_ed25519. The passphrase is like a password that adds increased security to your key, so it’s not recommended to leave it blank. You will be prompted to provide this passphrase from time to time to unlock your SSH key.

You can verify that the key was created by looking at your .ssh directory:

ls -la ~/.ssh

-rw-------  1 erika erika  464 Sep 23 19:48 id_ed25519
-rw-r--r--  1 erika erika  102 Sep 23 19:48 id_ed25519.pub

The id_ed25519.pub file is the public portion of your SSH key. You’ll use the content of this file to set up your SSH key within GitHub. The id_ed25519 file without extension is the private portion of your SSH key, and should never be shared.

Adding an SSH Key to your GitHub Account

To add your SSH key to your GitHub account, access the menu “SSH and GPG Keys” under your Settings.

Click on the “New SSH Key” button. On the screen that appears, you’ll be asked to provide a title for your key, and the public key contents. Leave the key type as “Authentication Key”. If you created your SSH key following the instructions on this guide, this is how you can obtain the contents of the public key:

cat ~/.ssh/id_ed25519.pub

Copy the full output to the “Key” field.

Click on the “Add SSH Key” to confirm.

With the key added, you are now ready to pull repositories from GitHub via SSH.

Cloning a GitHub Repository

You’ll now pull your special GitHub repository to your local system, so that you’re able to edit your README offline. Access your GitHub profile and go to your special repository. You can also access your repo directly with the address https://github.com/your-github-username/your-github-username.

Click on the green “Code” button, then click on the “SSH” tab under “Clone”. Copy the URL that starts with git@ in the text box.

Then, go to your terminal to clone the repository to your local machine:

git clone git@github.com:boredcatmom/boredcatmom.git

You may be prompted to provide your SSH key passphrase. You should get output similar to this:

Cloning into 'boredcatmom'...
remote: Enumerating objects: 3, done.
remote: Counting objects: 100% (3/3), done.
remote: Compressing objects: 100% (2/2), done.
remote: Total 3 (delta 0), reused 0 (delta 0), pack-reused 0 (from 0)
Receiving objects: 100% (3/3), done.

You can now access your repository files directly from a text or code editor or from your terminal.

❯ ls boredcatmom
README.md

Committing and Pushing your Changes

After making the changes you want in your README.md file, it is time to commit your changes and push them back to the remote repository. Let’s review the Git workflow with this image:

This will be similar to what we did in the first article in this series, when we initiated an empty Git repository and committed a file to it. To see the current repository status, run:

git status

This should indicate that the README.md file was modified, but its not yet staged for commit. To add the file to the commit stage, run:

git add README.md

Then, commit your changes with:

git commit -m "updating readme"

Now you can finally push your commit to the remote repository:

git push origin main

Again, you may be prompted to provide the passphrase to your SSH keypair. You should get output similar to this:

Enumerating objects: 5, done.
Counting objects: 100% (5/5), done.
Delta compression using up to 8 threads
Compressing objects: 100% (2/2), done.
Writing objects: 100% (3/3), 1.36 KiB | 1.36 MiB/s, done.
Total 3 (delta 1), reused 0 (delta 0), pack-reused 0
remote: Resolving deltas: 100% (1/1), completed with 1 local object.
To github.com:boredcatmom/boredcatmom.git
   691417c..26edb28  main -> main

Now, if you reload your GitHub profile, it should reflect the changes made to the README file.

Congratulations! You made your first push. Now you know how to clone a repository, make changes, and send them back to the remote repository.

Creating new Repositories and Connecting Existing Repositories to GitHub

Remember the testgit local repository from the first part of this series? That repository was not connected with any remote repo, so there was nowhere to push. Now that you have your GitHub account set up, you can create an empty repository and connect it with your local testgit repo. Instead of cloning the remote repo locally, you’ll configure your existing local repository to use the GitHub remote repo as upstream. In the context of Git and GitHub, "upstream" or “origin” refers to the original or main repository from which your local repository was created, and where changes should be sent. That’s why we run git push origin main when we want to push changes to the remote main branch.

To test this out, go to your GitHub dashboard at github.com and click on the + button on the top right, then select “New Repository”.

You’ll be redirected to a form to create a new repository. Choose a name for it – it doesn’t need to be the same name as your local git repo. Add a description if you want, and leave all other fields unchecked. Click on the “Create repository” button when you’re ready.

Once the repo is created, and because it is empty, it will show you information about how to connect this repo with your local Git setup. Grab the repository’s SSH URL, we’ll need it to configure your local testgit repo.

Then, go to your terminal and access the repo that was previously initialized::

cd ~/testgit

You’ll now run a command that will connect this repo with a remote one that will now be the origin.

git remote add origin git@github.com:boredcatmom/sandbox.git

This command will not give you any output. To update the remote repository and set your local repo to track the remote main branch as its upstream, run:

git push -u origin main

Enumerating objects: 3, done.
Counting objects: 100% (3/3), done.
Writing objects: 100% (3/3), 1.24 KiB | 1.24 MiB/s, done.
Total 3 (delta 0), reused 0 (delta 0), pack-reused 0
To github.com:boredcatmom/sandbox.git
 * [new branch]     main -> main
branch 'main' set up to track 'origin/main'.

If you reload your repository page on GitHub, it should now have a single readme.txt file that says “Git Crash Course”. You effectively copied your local repo and all its history to the brand-new repository you created.

Conclusion

In this article, you learned how to clone repositories and push your changes back to GitHub, and you also learned how to connect a local git repository to a remote GitHub repository.

In the next part of this series, we’ll learn about Git branches and how to collaborate with other developers and work together in the same repository.

Creating and Customizing your GitHub Profile

Erika Heidi — Tue, 19 Nov 2024 17:46:19 +0000

Continuing our crash course into Git and GitHub, we’ll now learn more about GitHub and how to establish your presence in this platform, where you can start sharing your code and contributing to open source projects.

GitHub is a leading platform for software development and version control, and has revolutionized the way developers collaborate and contribute to open source projects. As a centralized repository for code, GitHub facilitates seamless version tracking, allowing multiple developers to work on a single project simultaneously. Its intuitive interface, branching and merging features, and issue tracking capabilities make it an indispensable tool for developers of all skill levels. Moreover, GitHub fosters a vibrant community where developers can share ideas, learn from one another, and contribute to a vast array of open source projects.

In this guide for beginners, you’ll learn how to create a new GitHub account and how to customize your profile.

Creating a GitHub Account

If you don’t have yet an account on GitHub, now is the time to sign up. Click on the “sign up” button on the top right, and follow the instructions. You’ll need to provide a valid email address, and then choose a username and password.

After that, you’ll be asked to verify your account by solving a puzzle; this is to make it harder for spam accounts and bad actors to create accounts on the platform. Once you complete the puzzle and verify you’re not a “robot”, you’ll be asked to confirm your email address with a code that was sent to your inbox. After confirming, you should get a message informing you that your account was created successfully, and you can now log in to the platform.

After logging in, you’ll be asked a couple of questions so that GitHub can provide you with a more customized experience.

Then, you’ll be asked to choose between Free or Pro. If you are a student, you can also apply for the GitHub Student Pack, which will give you access to pro features for free. You can always start with the free account and upgrade later on.

After clicking on “Continue for free”, you will be redirected to your dashboard. From here you can create your first project or start exploring open source projects and repositories.

Customizing your Profile

The next step is to customize your profile information. To access the user menu, click on your avatar on the top right of the screen. In this menu, you’ll have quick access to all your account settings and resources.

To customize your profile, access the “Settings” item from the menu. In this page, you can customize your display name, bio, pronouns, and URLs / links. You can also change your avatar here.

To preview your profile after saving your changes, use the “Go to your profile” button on the top right, or go to the user menu and access “Your Profile”.

Creating a README to Further Customize your Profile

If you check your profile now, it will look pretty basic:

You can further customize your profile by creating a profile README, which is a markdown file that must be committed to a special repository with the same name as your username.

The easiest way to create this file is by going back to your dashboard at github.com and using the shortcut available in your Home section. Click on the “Create” button under “Introduce yourself with a profile README”:

You can now use the web editor to fill in your profile information in Markdown format. Use the “preview” button to preview your changes.

Looking for inspiration? Check the Awesome GitHub Profile Readme repository, which contains a curated list of GitHub profiles with nice README customizations that you can use as reference to build your own.

When you are satisfied with your README, click on the “Commit changes” button. A pop-up window will appear where you can customize your commit message.

When you click on “Commit changes”, the file will be committed to your special repository, and your profile will now render this content automatically. Hooray! You just learned a new way to make commits directly from the GitHub interface.

Notice that GitHub automatically created your special repository for you, and it will now be listed within your profile. Whenever you want to change your profile, go to this repository and edit the README.md file in it.

Conclusion

In this article, you learned how to create your GitHub account, how to customize your profile basic information, and how to create a custom section for it using a profile README.

In the next part of this series, you’ll learn how to pull this special repository into your local machine, so that you can work on your README offline, and then push these changes back to the remote repository.

An Introduction to Version Control and Git

Erika Heidi — Tue, 19 Nov 2024 17:45:04 +0000

Git is a powerful version control system that allows developers to track changes to code, collaborate with others, and manage multiple versions of a project. By mastering Git in the command line, developers gain the flexibility to perform various tasks efficiently, such as creating and switching between branches, resolving merge conflicts, and managing remote repositories. Additionally, familiarity with the command line provides a deeper understanding of Git's inner workings, enabling developers to troubleshoot issues and customize their workflows more effectively.

In this guide, beginners can learn about version control and how to get started with Git. To follow along, you’ll need access to a terminal and administrative privileges to install Git.

Overview

In a nutshell, version control is a system that allows you to track changes to files over time. This is useful for a variety of reasons, including:

Collaboration: Version control allows multiple people to work on the same files at the same time without overwriting each other's changes.
History: Version control keeps a history of all changes made to files, so you can see who made a change, when they made it, and why.
Rollback: Version control allows you to roll back to a previous version of a file if you make a mistake.

Git is a popular version control tool widely used for software development, but it can also be used for any type of project that involves managing multiple files. Git is designed to be efficient, flexible, and easy to use. It is a powerful tool that can help you to manage your projects more effectively.

Installing and Configuring Git

The official Git documentation has detailed instructions on how to install Git on all supported systems. On Ubuntu, you could run the following to get Git installed:

sudo apt update && sudo apt install git

To verify that the installation was successful, you can run:

git --version

Once you have Git installed, you’ll need to configure it with your name and email:

# Set your Git name
git config --global user.name "Your Name"

# Set your Git email
git config --global user.email "your@email.com"

# Configures default initial branch
git config --global init.defaultBranch "main"

Now you can start using Git!

The Basic Git Workflow

The basic Git workflow involves a cycle of making changes to files, staging those changes, committing them to your local repository, and then pushing them to a remote repository. Staging changes allows you to group together related changes before committing them. Committing changes creates a snapshot of your project at a specific point in time, along with a message describing the changes. Pushing changes to a remote repository makes them available to other collaborators and backs up your work in case something happens to your local repository. This cycle allows you to track changes, collaborate with others, and easily revert to previous versions of your project.

The image shows an analogy for the git workflow using letters. When you're working on the contents of your letter, you have unstaged changes. When you're ready, you'll add the letter to an envelope, and that's the equivalent of adding files to your staging area. Finally, you'll commit your changes by closing the letter and adding a stamp on it. After all that, you still need to push your changes to the remote repository, which is the equivalent of pushing your letter into a mailbox.

Creating your First Git Repository

We’ll now cover some basic Git commands to get you started and demonstrate the Git workflow.

Create a test directory and cd into it:

mkdir testgit && cd testgit

Next, initiate an empy git repository:

git init

You should get output similar to this:

Initialized empty Git repository in /home/erika/testgit/.git/

All files in this directory are now being tracked by Git. Create a new file so that we can try a commit:

echo "Git Crash Course" > readme.txt

Now, if you check the status of the repository, you’ll notice the new readme.txt file listed as untracked:

git status

You’ll get output like this:

On branch main

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)
    readme.txt

nothing added to commit but untracked files present (use "git add" to track)

As the message suggests, you can add files to be later committed with the git add command:

git add readme.txt

Now, if you run git status again, you’ll notice that the readme.txt file has moved to staged, which means it is now part of the changes that should be committed. The output also points out this is a new file, with no previous history to Git.

On branch main

No commits yet

Changes to be committed:
  (use "git rm --cached <file>..." to unstage)
    new file:   readme.txt

To commit changes, you can use the following command, which commits staged files and uses an inline message to identify this commit:

git commit -m "first commit"

You’ll get output similar to this:

[main (root-commit) 8e822c2] first commit
 1 file changed, 1 insertion(+)
 create mode 100644 readme.txt

Hooray 🎉 You just created your first commit. You can check all recent changes in a repository with the git log command:

git log

You should get output similar to this, showing your first commit to the repo:

commit 8e822c2c3b8b2872da87c6716f426282bb8a6340 (HEAD -> main)
Author: Erika Heidi <erika@erikaheidi.com>
Date:   Thu Nov 14 19:30:35 2024 +0100

    first commit
(END)

To exit the log view, press q.

It’s worth noting that all these changes are only being tracked locally. There is no remote repository linked, so everything is running on your local machine. If you delete the testgit folder, nothing will be saved. In a more real world scenario, you would be running an additional command to push your commit to a remote repository. You'll learn how to do that in a later part of this series.

Conclusion

In this article, you learned the basics about Git, including how to initialize an empty Git repository, how to stage changes, and how to commit them. In the next part of this series, you'll create a new GitHub account and customize your profile with a profile README.

Running WordPress on Containers

Erika Heidi — Wed, 18 Sep 2024 17:49:16 +0000

Powering more than 40% of the top 10 million websites on the Internet today according to WikiPedia, WordPress continues to be one of the most popular content management systems in the world. Though its core components remain primarily PHP and MySQL/MariaDB, a lot has changed in the past 20 years in terms of infrastructure and hosting options.

Containers offer several significant benefits for WordPress environments. They provide isolation, ensuring that each WordPress instance operates independently without interfering with others. This enhances security and prevents conflicts. Additionally, containers enable scalability, allowing easy horizontal scaling of WordPress applications to meet increased demand. This is particularly useful for handling traffic spikes or seasonal fluctuations. Furthermore, containers offer portability, making it simple to move WordPress environments between different hosting providers or infrastructure. This flexibility can be valuable for disaster recovery and migration purposes. It also facilitates the use (and reuse) of disposable environments that can be shared across different stages, from build and development to test and production.

In this post, we'll discuss some considerations around running WordPress on containers, and how to better choose a base image for your specific WordPress needs.

Migrating to Container-Based Environments

If you are a long-time WordPress administrator, you may have experience in setting up LAMP or LEMP systems (Linux / PHP / MySQL or MariaDB, and either Apache or Nginx as web server). Understanding how these services communicate between each other is helpful in order to create a suitable environment based on containers.

You can create a container-based LEMP environment to run locally on your machine using Docker Compose. This is a great starting point for anyone migrating from bare metal servers or VPSs to containerized environments.

This post has a nice overview of Docker development environments for beginners. The Docker Compose documentation has guidance on how to set up a Docker Compose file to orchestrate multiple container-based services.

Choosing a WordPress Base Image

Using containers is a good starting point to create safer WordPress runtime environments, but it is important to choose your base image carefully. There are a few important factors you need to take into consideration when choosing a base container image for your WordPress environments:

Image Provider
Make sure you're using images from a reliable provider, and avoid using images from unknown sources. When using images from Docker Hub, always give preference to providers that are verified Docker publishers, since those go through a vetting process and comprise high-quality images from commercial publishers verified by Docker.

Features and Ease of Use
Naturally, you want an image that has the features necessary for creating (or re-creating) your own WordPress setup, which might include custom plugins and themes. In addition to what's required to run WordPress, look for an image that has features to facilitate customization and migration.

Update Frequency and Patching
Ensure the image is frequently updated to address security vulnerabilities and incorporate the latest WordPress features.
Look for providers with a clear patching policy and commitment to timely updates.

Size and Attack Surface
Size sometimes matter. For containers, size might be an indication of the amount of packages included in the image. From a vulnerability standpoint, less is better, because it means there is less surface for a potential attack. Make sure the image has what is needed to run WordPress, without bloat from unnecessary software.

Number of Vulnerabilities
Last but not least, be on the lookout for container images with less vulnerabilities. Although this might sound like a no-brainer, many people don't take into consideration that containers can be exploited almost in the same way as a VPS or bare metal server. In the next section, we'll have a better look at what CVEs are and how to scan your container images for known CVEs.

CVEs Explained

CVEs, or Common Vulnerabilities and Exposures, are publicly known security flaws in software or hardware. These vulnerabilities can be exploited by malicious actors to gain unauthorized access, steal data, or disrupt systems. The severity of a CVE can range from minor inconveniences to catastrophic breaches. Unpatched CVEs pose significant risks to organizations of all sizes, making it imperative to stay informed and address them promptly.

We'll now see how to use Grype to scan container images for CVEs, which will help you make an informed choice when deciding on which base image to use for your WordPress environments.

Scanning WordPress Images for CVEs with Grype

Grype is a popular open source CVE scanner that scans for known vulnerabilities in container images and filesystems. At the time of this writing, the latest release is 0.80.1 and you can find packages for most operating systems in their releases page.

Before running the Grype scanner on container images, use docker pull to get the latest version available for that image. We'll run comparisons between the following base images available on Docker Hub:

wordpress:latest
wordpress:php8.3-fpm⁠-alpine
bitnami/wordpress
chainguard/wordpress

To scan an image, run grype followed by the image registry address. For example:



grype wordpress

And this will scan the default latest WordPress image on Docker Hub. You'll get output including the following contents:

A summary of what was detected in the image, including number of packages, files, and executables
The total amount of vulnerabilities found, which is calculated as total not-fixed - total ignored + total fixed
Total vulnerabilities grouped by severity and by status
The full list of detected CVEs including number and severity

The following chart contains a summary of scan results for the images previously listed as of September 18, 2024. You can run grype against each of the listed images and check the data for yourself as well. This includes only CVEs marked as low, medium, high, and critical scores.

Results Summary:

wordpress:latest: low: 9, medium: 175, high: 63, critical: 8
wordpress:php8.3-fpm⁠-alpine: low: 7, medium: 144, high: 106, critical: 30
bitnami/wordpress: low: 8, medium: 46, high: 27, critical: 8
chainguard/wordpress: medium: 1

Yes, that's what you read. Run the scans on your own machine and you'll get the same numbers.

Why does the Chainguard WordPress image has only 1 CVE? That's a very good question. I know a couple things about this subject, since I have built that image ;)

I will explain everything you need to know about Chainguard's 1-CVE WordPress image at my upcoming Learning Lab. This is a free online event happening on the 24th of September, and you can register here to participate.

Resources to Learn More

If you are curious about Chainguard Images and Wolfi, check out Chainguard Academy, where me and my colleagues at the Developer Enablement team from Chainguard share documentation and tutorials about software supply chain security, container image security, Wolfi and Chaiguard Images.

Our WordPress getting started guide has detailed information on how to get started with Chainguard's WordPress image. This content is also available in video format here:

Conclusion

Running WordPress on containerized environments has many advantages, but it's important to choose your base container images wisely, since some popular options are riddled with vulnerabilities. We've seen some important things to take into account when choosing an image, and how to use the grype CVE scanner to verify how vulnerable an image might be to known CVEs.

From here, you can make your own evaluation and decide what to use. If you would like to learn more about the Chainguard WordPress image, you can attend our upcoming Learning Lab here.

Migrating to Chainguard Images: less CVEs for safer container runtimes

Erika Heidi — Wed, 17 Apr 2024 17:25:44 +0000

Software supply chain attacks have become common in the industry lately, with the latest episode featuring the infamous CVE-202403904 and the xz's backdoors.

Whether malicious or unintentional, a CVE can pose as severe risk to organizations relying on a piece of affected software. The CVE database has over 200.000 entries and it just scratches the surface, since unreported exploitable vulnerabilities (a.k.a. zero-days) are a fairly common occurrence in the hacking scene.

For a long time, this was not a developer's concern. But with the explosion of open source third-party software dependencies, it is virtually impossible to keep track and know everything that is included within a software artifact, whether we're talking about a single package or a whole operating system. Just as in other industries, a compromise in any point of your supply chain represents an issue that may be exploited by bad actors.

Less CVEs for safer container runtimes

It is a no-brainer that using a container image with less CVEs is better for security. Reducing the surface for attack has proven to be an effective way of creating safer container runtimes.

Consider the php:alpine image, which is known for being a smaller image when compared to Debian and Ubuntu variants:

Now let's have a look at this image's Chainguard equivalent, the cgr.dev/chainguard/php:latest image:

It's worth noting that these numbers fluctuate naturally as new CVEs come out and new patches are available by package vendors. The following graph shows a 30-day comparison between php:latest and cgr.dev/chainguard/php, for another perspective (live version available here):

So how is this possible? We could say the secret sauce of Chainguard Images is a drastically reduced surface for attack, but that is just one of the many ingredients that make these images stand out in terms of container security. Provenance attestation is another important feature that provides a way to verify the image comes from where it should.

Resources to Learn More

The Migrating Dockerfiles to Chainguard Images guide has a high-level overview with a couple examples showing how you can migrate from other base images to Chainguard Images. We have also a dedicated PHP Migration Guide you can use as reference when migrating PHP Dockerfiles to Chainguard Images.

If you'd prefer a more hands-on experience, I'll be presenting a Learning Labs workshop next week (Tuesday April 23, 12PM ET / 6PM CEST) about this topic. We'll talk a bit about CVEs, software supply chain security, and then I'll dive into some live demos showing all you need to know for a streamlined migration process. Hope to see you there! You can register here to save a spot.

Setting Up Obsidian for Content Planning and Project Management

Erika Heidi — Mon, 11 Mar 2024 18:08:54 +0000

Obsidian is a writing application created to allow for offline / private note taking in markdown format, in an interface that looks a lot like our regular programming IDE. It is very flexible, with a good collection of community plugins that you can use to customize Obsidian to your heart contents.

I recently started using Obsidian at work for daily / weekly notes and it's being super helpful to keep me organized. I am now setting up Obsidian on my personal laptop to help me keep track of ideas and side projects. In this post, I share my setup and my custom templates to facilitate that.

1. Installing Obsidian

The first step is to get Obsidian installed on your computer. Check their downloads page to download and install the appropriate version for your system.

2. Customizing Obsidian Appearance

Once you get Obsidian installed and when you open it for the first time, you will get a screen like this, asking you to create a new Vault or use an existing directory as vault. A "Vault" is a folder where your markdown documents will live.

You can specify where to create your Vault. I created a folder called "My Projects" under my "Documents" and used that. After confirming the location of your Vault, you'll see Obsidian's default interface.

I prefer a dark color scheme, so I changed it in Settings -> Appearance -> Base color scheme.

Further down in the same screen, I increased the interface zoom in Advanced -> Zoom Level.

After that and still on the Settings window, I went to Community Plugins-> Turn on Community Plugins to enable community plugins. We'll need this to install some nice plugins that will help us make the most of Obsidian.

At this point, Obsidian is already functional, so you can start creating folders and organizing markdown documents. In the next step we'll install a few plugins to help with content planning and project management.

3. Installing Templater and Tasks plugins

Obsidian has a large collection of community-contributed plugins to serve various user needs. For this guide, we'll install Templater and Tasks, two plugins that can be really powerful when combined to create notes and task lists.

Templater

It defines a templating language that lets you insert variables and functions results into your notes. It will also let you execute JavaScript code manipulating those variables and functions.

We'll use Templater to set up a few default templates per folder. So when you create a new "tutorial" type of content, it will automatically use the designated "tutorial" template. We'll do the same for projects.

First, create a new folder for your templates in your Vault. You can call it "Templates". Then, go to Settings -> Templater and set up the Template folder location to the newly created directory. Also enable Trigger Templater on new file creation .

Now you can start creating templates for different content types, projects, etc, and match each template with a content folder. We'll set up two templates in this guide: Project and Content.

Create a new file in your Templates folder and call it "Project". You can use the following template as base, customizing it to better fit your needs:



---
name: Project Name
createdAt: <% tp.date.now() %>
description: A project to do X in Z
tags:
  - tag1
  - tag2
  - tag3
---

## To Do
- [ ] Task 01 ⏫ 
- [ ] Task 02
- [ ] Task 03

## Milestones

- Milestone 1
- Milestone 2
- Milestone 3 

## Ideas
- Idea 01
- Idea 02
- Idea 03

Create another file and call it "Content" - this will be your content template. You can use the following as base:



---
title: How to Do This Thing
description: Learn how to do this thing on Linux
tags:
  - tag1
  - tag2
  - tag3
---
## Introduction
Introduce the thing.

##  1. Doing the first thing
Explain how to do the first step.

## 2. Doing a second thing
Explain how to do the second step.

## 3. Doing a third thing
Explain how to do the third step.

## Conclusion
Quick recap, final remarks, and how to learn more.

---

### Content Launch Checklist
- [ ] Content published to DEV
- [ ] Content shared on X/Twitter
- [ ] Content shared on LinkedIn
- [ ] Short video published on Reels (Instagram)
- [ ] Short video published on YouTube Shorts
- [ ] Long video shared on YouTube
- [ ] Video shared on YouTube

After setting up both templates, create a "Project" folder to save your project pages and a "Content" folder to save tutorial pages. Then go to Settings -> Templater then navigate to Folder Templates to set up the Project and Tutorial content types. You should now associate each folder with its corresponding template.

After applying the changes, check that everything works as expected by right-clicking on the content or project folder and creating a new note there. The new note should be created using its designated template.

Tasks

Track tasks across your entire vault. Query them and mark them as done wherever you want. Supports due dates, recurring tasks (repetition), done dates, sub-set of checklist items, and filtering.

The Tasks plugin is very powerful because it allows you to create elaborate task lists and search/filter tasks from your whole Vault to be listed in a single document. You can, for instance, list all your TO DO tasks from all your projects, using various filters to surface only what's relevant or high priority.

As you may have noticed in the previous step where we set up Templater templates, we added a TO DO list to the Project template and a Content Launch Checklist to the Tutorial template. We can surface these tasks on another markdown document that we can use to have a high-level overview of all your open tasks.

Create a new file in the root of your vault and call it "Tasks". Copy the following raw content to this file:




### Projects
```tasks
not done
filter by function task.file.folder === "Projects/"
```


###  Content
```tasks
not done
filter by function task.file.folder === "Content/"
```

Now when you change from editing mode to reading mode, you'll get two lists with your TO DO tasks from the "Projects" folder and the "Content" folder, similar to this:

You can create multiple pages like this with different search filters to give you complete visibility on your plans and tasks. Here I also created a "Completed Work" page to show tasks that are marked as "done". For that, you can use a simple query like the following:



```tasks
done
```

Check the Tasks plugin documentation to learn more about the powerful search features provided by the plugin.

Final Considerations

Obsidian is a powerful text writing application that allows users to customize it to their very specific needs. With a few plugins, you can turn your Obsidian into a powerful helper to plan and track content, new ideas, and projects.

In this guide we saw how to create a basic setup using the Templater and Tasks plugins to help you track your tasks for content creation and other projects in general. Based on what you learned here, you can further customize your folders and templates in a way that best suits your needs.

Creating an Automated Documentation Pipeline in PHP with Autodocs and GitHub Actions

Erika Heidi — Tue, 16 Jan 2024 15:13:22 +0000

Autodocs is a PHP library designed to facilitate building highly customizable automated docs based on markdown templates. Combined with a Minicli application, it provides a layer of abstraction and structure on top of which you can create your own documentation factory.

I created this project to help me keep up with the documentation needs for Chainguard Images, which now helps keeping more than a thousand doc pages up-to-date in a GitHub-based workflow with nightly runs.

Pages are defined as classes that follow a known interface. Data sources can be autoloaded as JSON cache files, a design that facilitates distributed setups where data comes from varied sources. This distributed approach facilitates integrating Autodocs with existing workflows and pipelines, especially when using GitHub Actions.

In this tutorial we'll create a demo Autodocs application to generate personal GitHub READMEs. If you'd prefer to skip the tutorial and go straight to the code, you can check the demo repository on GitHub.

1. Bootstrapping the Demo App

Let's start by creating the demo application. We're using the Minicli application template to provide more resources and organization when building out the app.

composer create-project minicli/minicli autodocs-demo

Once Composer is finished installing the new application dependencies, you should be able to enter the directory and run a quick test:

cd autodocs-demo
./minicli

You should get output like this, indicating that the Minicli application runs as expected:

❯ ./minicli


███╗   ███╗██╗███╗   ██╗██╗ ██████╗██╗     ██╗
████╗ ████║██║████╗  ██║██║██╔════╝██║     ██║
██╔████╔██║██║██╔██╗ ██║██║██║     ██║     ██║
██║╚██╔╝██║██║██║╚██╗██║██║██║     ██║     ██║
██║ ╚═╝ ██║██║██║ ╚████║██║╚██████╗███████╗██║
╚═╝     ╚═╝╚═╝╚═╝  ╚═══╝╚═╝ ╚═════╝╚══════╝╚═╝

Minimalist, dependency-free framework for building CLI-centric PHP applications

Now you can rename the executable to autodocs or a different name if you'd like:

mv minicli autodocs

Next, we want to include the autodocs library as a dependency within Composer:

composer require erikaheidi/autodocs

You now have all requirements set up and can proceed to configuring Autodocs.

2. Configuring Autodocs Options

Create a new configuration file to hold Autodocs settings. This should go in the config folder of your Minicli applicaiton:

touch config/autodocs.php

Autodocs expects an autodocs configuration entry with a few required settings:

templates_dir: where to find .tpl files that may be used as page templates. The use of templates is not mandatory, but it can be helpful to facilitate content layout updates without having to change page classes.
cache_dir: .json files in this directory will be automatically registered as a DataFeed object within the main Autodocs service.
output: location where to save built pages.
pages: an array with classes that should be registered as Reference Pages. These are the documentation pages that will be built at each run.
storage: (Optional) a class that implements StorageInterface, able to handle filesystem access to save and retrieve files. The default FileStorage is used when no option is defined.

For our demo, let's create a storage directory for templates, content, and cache:

mkdir -p storage/cache storage/templates storage/content

Next, open the file we created previously, config/autodocs.php, using your PHP editor of choice. Copy the following configuration to your file:

<?php

declare(strict_types=1);

use Autodocs\Page\ExamplePage;

return [
    'autodocs' => [
        // Pages to Build
        'pages' => [
            ExamplePage::class
        ],
        // Build Output Folder
        'output' => envconfig('AUTODOCS_OUTPUT', __DIR__.'/../storage/content'),
        // Cache Folder - where to look for cache json files
        'cache_dir' => envconfig('AUTODOCS_CACHE', __DIR__.'/../storage/cache'),
        // Templates directory
        'templates_dir' => envconfig('AUTODOCS_TEMPLATES', __DIR__.'/../storage/templates')
    ]
];

Save the file. Notice we registered an ExamplePage that is included for tests. We'll update this later on to include our custom pages.

3. Registering the Autodocs Service

With the config in place, you can now register the Autodocs service within the Minicli application.

Open the config/services.php file and make sure it looks like this, with the line including the Autodocs service class registered as autodocs:

<?php

declare(strict_types=1);

use Autodocs\Service\AutodocsService;

return [
    /****************************************************************************
     * Application Services
     * --------------------------------------------------------------------------
     *
     * The services to be loaded for your application.
     *****************************************************************************/

    'services' => [
        'autodocs' => AutodocsService::class,
    ],
];

Save the file. You can now start working on your build command, which we'll see in the next step.

4. Creating a Build Command

We'll now create a command to build our custom automated docs. This will build all pages defined in the pages autodocs config, which for now should be set to just include the ExamplePage. Once this simple example page builds, we can start working on our actual doc pages.

In Minicli, creating a command is just a matter of setting up some classes and directories in a pre-defined format. Start by creating a directory for your commands inside app/Commands:

mkdir app/Command/Build

Next, we'll create the command controller that will handle building the docs.

Create a new file called DefaultController.php inside the newly created app/Command/Build directory. In this class, we'll set up a method that will be called whenever we run ./autodocs build.

touch app/Command/Build/DefaultController.php

Open this file on your PHP editor of choice. You can start by copying the following skeleton for your controller class:

<?php

declare(strict_types=1);

namespace App\Command\Build;

use Minicli\Command\CommandController;

class DefaultController extends CommandController
{
    public function handle(): void
    {
        //build command action
    }
}

From the handle method, we can access the application, the configuration container, and all registered services. The logic here will depend on your documentation needs.

To build the included ExamplePage, update your handle method to the following code:

    public function handle(): void
    {
        /** @var AutodocsService $autodocs */
        $autodocs = $this->getApp()->autodocs;

        $this->info("Starting Build...");
        $autodocs->buildPages($this->getParam('pages') ?? "all");
        $this->info("Build finished. Output saved to " . $autodocs->config['output']);

    }

This will build the example page and save it in the location defined by output in Autodocs config.

Building the Docs

Now you should be able to run the build command with:

./autodocs build

You should get output like the following:

❯ ./autodocs build

Starting Build...

Build finished. Output saved to /home/erika/Projects/autodocs-demo/config/../storage/content

Check the output folder. You should find an example.md page there.

5. Creating Documentation Pages

In the previous step we created a build command and used it to build the included ExamplePage, which is a really simple page that basically outputs a title and a description. After having a look at how pages are defined, we'll create a custom page for our demo app.

5.1 Reference Pages

Reference Pages are models that represent a document and how it should be built. They should extend from the ReferencePage class (or implement ReferencePageInterface) and implement the following methods:

loadData - this method receives an optional $parameters array and should load any additional data required to build the page.
getName - must return a unique identifier that can be used later on to build only this type of page.
getContent - the actual content that will be saved.
getSavePath - the path where to save this file, to be used by the page builder.

It is easier to see how it works in practice, so this is what the ExamplePage looks like:

<?php

declare(strict_types=1);

namespace Autodocs\Page;

use Autodocs\DataFeed\JsonDataFeed;

class ExamplePage extends ReferencePage
{
    public JsonDataFeed $dataFeed;
    public function loadData(array $parameters = []): void
    {
        $this->dataFeed = new JsonDataFeed();
        $this->dataFeed->loadFromArray([
            'title' => 'example',
            'description' => 'description'
        ]);
    }

    public function getName(): string
    {
        return "example";
    }

    public function getContent(): string
    {
        return $this->dataFeed->json['title'].' - '.$this->dataFeed->json['description'];
    }

    public function getSavePath(): string
    {
        return 'example.md';
    }
}

This example creates a JsonDataFeed and loads it with static data. Instead, you could use JSON data files and have them automatically loaded by Autodocs - you just need to place the files in the path defined by the cache configuration option.

Next, we'll create our own custom documentation page using a simple JSON data source. For this demo, we'll generate a markdown page that can be used as your personal README on GitHub (the one that is rendered in your profile).

5.1 Creating a `ReadmePage`

The following ReadmePage class loads data from a JsonDataFeed that was pre-loaded into the application container. We'll set that JSON file in the next step.

The getContent method uses Stencil to render a template called readme.tpl with values obtained from the JSON data source.

<?php

declare(strict_types=1);

namespace App;

use Autodocs\DataFeed\JsonDataFeed;
use Autodocs\Page\ReferencePage;

class ReadmePage extends ReferencePage
{
    public JsonDataFeed $dataFeed;
    public function loadData(array $parameters = []): void
    {
        $this->dataFeed = $this->autodocs->getDataFeed('profile.json');
    }

    public function getName(): string
    {
        return "readme";
    }

    public function getContent(): string
    {
        return $this->autodocs->stencil->applyTemplate('readme', [
            'title' => $this->dataFeed->json['user'],
            'about' => $this->dataFeed->json['bio'],
            'projects_list' => $this->getProjects(),
        ]);
    }

    public function getProjects(): string
    {
        $content = "";
        foreach ($this->dataFeed->json['projects'] as $project => $info) {
            $content .= "- [{$project}]({$info['link']}): {$info['description']}\n"; // returns Markdown list
        }

        return $content;
    }

    public function getSavePath(): string
    {
        return 'README.md';
    }
}

When you're ready, copy these contents into your own app/ReadmePage.php and save the file. But don't run the build just yet; we still need to set up the JSON data source and the template file used by the ReadmePage class.

5.2 Setting up the `profile.json` Data Source

Next, we'll create a simple JSON file with some data to use when building the Readme page.

Create a new file called profile.json in your cache_path:

touch storage/cache/profile.json

Open the file in your editor of choice. Copy the following JSON skeleton and update the data with your own info:

{
  "user": "Erika Heidi",
  "bio": "Software and Documentation Engineer",
  "projects": {
    "minicli/minicli": {
      "description": "CLI framework for PHP",
      "link": "https://docs.minicli.dev"
     },
    "erikaheidi/autodocs": {
      "description": "Tiny framework for automating documentation",
      "link": "https://github.com/erikaheidi/autodocs/wiki"
    }
  }
}

Save the file when you're finished.

5.3 Setting Up the `readme.tpl` Template

Next, create the template file:

touch storage/templates/readme.tpl

Copy the following content to your template:

## {{ title }}

{{ about }}

## My Projects

{{ projects_list }}

Save the file when you're done.

5.4 Registering the `ReadmePage` within Autodocs Configuration

Now you just need to register your custom page within Autodocs configuration. Edit the config/autodocs.php file, and change the pages entry to include the new page. You can also remove the ExamplePage while you're at it. It should look like this when you're finished:


    'autodocs' => [
        // Pages to Build
        'pages' => [
            ReadmePage::class
        ],

Save the file when you're finished.

5.5 Building the `ReadmePage`

With the new page registered within the documentation, you can now proceed to build the ReadmePage:

./autodocs build

You should get output indicating that the page was successfully built. If should now have a readme.md file in your output folder with contents similar to this:

## Erika Heidi

Software and Documentation Engineer

## My PHP Projects

- [minicli/minicli](https://docs.minicli.dev): CLI framework for PHP
- [erikaheidi/autodocs](https://github.com/erikaheidi/autodocs/wiki): Tiny framework for automating documentation

6. Running the Demo with GitHub Actions (Optional)

We'll now create a workflow to run this demo on GitHub Actions. This is optional and requires you to set up your own repository with a copy of the project. You can also fork the original demo to your GitHub account and change the JSON data file to have your own info. Once you have your repository set up, go to Settings -> Actions -> General, scroll to the bottom of the page where you'll find the Workflow permissions section.

Then, enable "Read and Write permissions" and "Allow GitHub Actions to send Pull requests", so that the workflow can make changes and create a PR with the generated doc(s).

Our workflow will:

set up some environment variables that will overwrite default configuration values for Autodocs,
check out the repository,
install Composer dependencies using cache when available,
build the docs,
and send a pull request only when changes are detected.

name: Build Docs

on:
  workflow_dispatch:

env:
  AUTODOCS_OUTPUT: "${{ github.workspace }}"
  AUTODOCS_CACHE: "${{ github.workspace }}/storage/cache"
  AUTODOCS_TEMPLATES: "${{ github.workspace }}/storage/templates"
jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - uses: actions/checkout@v3

    - name: Cache Composer packages
      id: composer-cache
      uses: actions/cache@v2
      with:
        path: vendor
        key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
        restore-keys: |
          ${{ runner.os }}-php-

    # Install Dependencies
    - name: Install dependencies
      run: composer install --prefer-dist --no-progress

    # Build Docs
    - name: Run Autodocs
      run: ./autodocs build

    # Send a Pull Request
    - name: Create a PR
      uses: peter-evans/create-pull-request@v5
      id: cpr
      with:
        path: "${{ github.workspace }}"
        commit-message: Update content
        title: "[AutoDocs] Updated README"
        body: "README auto-update"
        labels: |
          documentation
          automated

You can save this file to .github/workflows/autodocs.yaml. Don't forget to commit and push it to your repository. Once the file is there, go to Actions and select the Build Docs action on the left. This workflow is not set to run on schedule, instead it uses the workflow_dispatcher trigger which can only be triggered from the repository page.

Click on the "Run Workflow" button on the right, then confirm to run the workflow for the first time. If the build passes as it should, you'll get a new pull request on your repository:

Based on this simplified demo, you can elaborate your workflow to auto-generate your profile.json data and have your README always fresh. Maybe pull your latest posts from DEV or a blog feed? Show off your favorite projects, or highlight your sponsors? The only limit is your imagination :)

Final Considerations

Documentation is a living organism, it changes and evolves as projects grow. After quite a few years working in the field of technical writing and documentation, I believe good documentation needs flexibility, context, and human input. These are hard to combine in a one-size-fits-all software to magically create docs.

Autodocs doesn't magically generate docs for you, that was never the intention. Instead, it provides a very thin layer of abstractions to give you enough structure to engineer your super custom docs and also to scale up your documentation using a distributed approach to data sourcing.

If you want to see a more complex implementation to have an idea of what Autodocs is capable, check Chainguard's Images Autodocs project on GitHub.

Development Environments with Docker

Erika Heidi — Thu, 16 Nov 2023 19:13:37 +0000

Docker is a software used to build and run containers. Unlike virtual machines, containers do not emulate an entire operating system, relying on the host OS to provide an isolated filesystem that consumes less resources than traditional VMs, but still provide a fully functional runtime based on a chosen operating system.

The build steps necessary to (re)create a Docker container image are defined in a Dockerfile. This file may contain special instructions to install packages, create users, and run arbitrary system commands.

Container images can be hosted in a remote registry that allow images to be pulled from different locations. The default Docker registry is Docker Hub, but there are many others. When using images from registries other than Docker Hub, you'll need to specify the registry URL along the image identifier.

Pulling Images from a Registry

The pull command is used to pull images from a remote registry. It is not mandatory to run this command before running an image, as the pull will happen automatically. However, if you already have a local copy of an image, you'll need to run the pull command in order to obtain an updated version of the image.

docker pull registry/image

For example, this will pull the PHP Chainguard Image to your local machine:

docker pull cgr.dev/chainguard/php

You should see output similar to this:

Using default tag: latest
latest: Pulling from chainguard/php
1e4853eb9712: Pull complete 
Digest: sha256:387acb900179de11ca5a56c3ebbb6f29d2df88cb488d50fc9736ab085f27520d
Status: Downloaded newer image for cgr.dev/chainguard/php:latest
cgr.dev/chainguard/php:latest

Running Containers

The run command is used to execute the entry point defined by your image Dockerfile. Depending on the image and how it is used, you may need to provide additional parameters to the command.

docker run registry/image

For example, the following command will execute the PHP image we pulled in the previous section, with the --version flag to obtain the PHP version:

docker run cgr.dev/chainguard/php --version

PHP 8.2.12 (cli) (built: Nov 15 2023 15:30:03) (NTS)
Copyright (c) The PHP Group
Zend Engine v4.2.12, Copyright (c) Zend Technologies

Running Containers in Interactive Mode

Many (maybe even most) container images run a single command and are terminated afterwards. It is the case with regular PHP images that are meant to run scripts. There is no interaction once the process of execution is initiated.

Some images will require some type of interaction from the user. That is often the case with images that run an interactive application such as bash. In those cases, you'll need to provide the -it argument when running Docker:

docker run -it registry/image

For example, this will execute the wolfi-base image and land you in a shell inside the newly created container:

docker run -it cgr.dev/chainguard/wolfi-base

Running Ephemeral Containers

To remove a container immediately after it is terminated, add the -rm parameter to the docker run command:

docker run --rm registry/image

This is especially useful for running quick commands that don't generate relevant output that needs to be shared or persisted, as with our first example that checked for the PHP version. We could rewrite that command to the following:

docker run --rm cgr.dev/chainguard/php --version

And this will prevent Docker from keeping the state of this container, which is good for saving resources.

Checking Container Status

To have a full list of active and inactive containers currently registered in the system, run:

docker ps -a

Note: When the -a parameter is not provided, Docker will list only containers that are currently running.

You should get output similar to this:

CONTAINER ID   IMAGE                    COMMAND                CREATED          STATUS                      PORTS     NAMES
26272c21399c   cgr.dev/chainguard/php   "/bin/php --version"   10 minutes ago   Exited (0) 10 minutes ago             musing_hermann

The first time we executed the command to obtain the PHP version of the container, we didn't use the --rm flag. That's why the container is listed here - it's inactive, but its state is saved.

Using Volume Shares

When running development environments, it's crucial that you're able to edit your code in your local machine, while being able to execute and test it inside the container. To enable that, you can use Docker volumes. Volumes are used to share the contents of a predefined path in your host machine to a location inside the container.

The following command will create a volume sharing the contents of LOCAL_FOLDER in the host machine with REMOTE_FOLDER inside the container.

docker run -v LOCAL_FOLDER:REMOTE_FOLDER registry/image

Use Case and Example

Let's say you want to run a PHP script without having to install PHP (could be any other language). You want to be able to make changes to the file and test it in an isolated environment.

Create a folder in your home directory for this demo:

mkdir ~/docker-demo
cd ~/docker-demo

Next, create a new file and copy the following contents to it:

<?php
echo "Testing Docker PHP Dev Env";
print_r($argv);

Save the file as demo.php.

Now you can use a Docker image to run this code. The following command will create an ephemeral container to execute code shared inside the container:

docker run --rm -v ${PWD}:/app cgr.dev/chainguard/php demo.php

The ${PWD} shell variable contains the current directory location. The volume will share the current directory with the /app location in the container, which is the workdir (the default directory) for that image. With the files shared in the default workdir, you can refer to the script simply as demo.php.

Purging Docker Resources

Some resources are not removed once a container is terminated; that is the case with named volumes. Images can also leave a big footprint in your system, think gygabites of space from unused layers and old images.

The prune command can be used to clean up unused resources and free up space occupied by them. For instance, to purge unused volumes:

docker volume prune

WARNING! This will remove anonymous local volumes not used by at least one container.
Are you sure you want to continue? [y/N]

The same logic applies to images and networks. To perform a complete system purge, run:

docker system prune

You should get a warning message confirming what is going to be removed. Type y to confirm.

WARNING! This will remove:
  - all stopped containers
  - all networks not used by at least one container
  - all dangling images
  - all dangling build cache

Are you sure you want to continue? [y/N]

Unused resources accumulate with time, so it's good to run this command every once in a while. Depending on how you're using Docker, you may be able to free up a lot of disk space with this command.

Resources to Learn More

The What are Containers? guide from Chainguard Academy has a nice high level overview of containers and images. For more technical specifications and reference docs, check the official Docker Documentation which covers all components in the Docker container ecosystem.

For considerations about container security, check this Academy guide on Selecting a Base Image and the introduction to Software Supply Chain Security, which should give you a better understanding of security considerations when bringing your images to Production.

Bonus: Docker Cheat Sheet

Get Involved with Chainguard Projects for Hacktoberfest 2023

Erika Heidi — Wed, 18 Oct 2023 15:58:33 +0000

Open source has always been at the core of what Chainguard does, which is evidenced by projects such as Sigstore and Wolfi. From image building to automated documentation, the majority of the code we write is open source, from the very beginning.

In this month of October, the Developer Enablement team at Chainguard would like to invite Hacktoberfest participants to get involved with our open source projects. We have good first issues and a welcoming team ready to help with any questions you may have.

If you're interested in containers and Linux, you may be interested in Wolfi, our community Linux undistro built for containers. We appreciate your help in keeping Wolfi-bot accountable - it doesn't always get things right 😅

If you'd like to help with documentation, we welcome your help with READMEs in the Chainguard Images repository.

Contributing to Wolfi

The Wolfi Linux undistro is an open source project primarily maintained by Chainguard, but with community contributors from all over the world. Wolfi packages live in the github.com/wolfi-dev/os repository, where we have established a thorough automation process to validate new package builds, check for available package updates, and automatically send PRs when new versions are available. In fact, the Wolfi-bot is a top contributor to the project, but it doesn't always get things right at first.

This year we invite Hacktoberfest participants to help with broken automated PRs from the Wolfi-bot.

Identifying Broken PRs

The broken Wolfi-bot PRs are easy to spot — they are tagged as automated-pr and request-update and have an red X icon next to it, indicating that one or more CI checks didn't pass. This is typically due to a build issue that needs to be manually debugged and fixed - maybe a new package version introduces a new dependency that is not met at build time, or something has changed in the make / build process for that package.

We have created a number of issues to fix these broken PRs. You can find them in the repo by searching for issues tagged as hacktoberfest.

What we expect from contributions

Choose an issue tagged as hacktoberfest from the list. Make sure to leave a comment on the issue so that others know you are working on it.
Create a new PR with your changes, so that we can tag it with the hacktoberfest-accepted label and make it a valid PR for Hacktoberfest.

Check also the Wolfi contributing guide for more information on how to get started.

Contributing to Chainguard Images

The public https://github.com/chainguard-images/images repository is an open source repository containing the configurations for all public Chainguard Images. With the number of images growing every day, it is hard to keep up with documentation needs. This year we invite Hacktoberfest participants to test our images and help update their READMEs, which are used for images documentation living in Chainguard Academy.

What we expect from contributions:

Choose one of the listed issues.
Test the image on your local environment.
Update the image README with instructions on how to use it and any other important information that you think users should know. You should follow the README template for keeping READMEs consistent.
Optionally, write a test for the image. Check the "Tests" section of our Best Practices doc for more details on how to go about that.

When you're finished, create a PR to the Chainguard Images repository with your updated README, so that we can tag it with the hacktoberfest-accepted label and make it a valid PR for Hacktoberfest.

Contributing to Chainguard Academy

You are also welcome to send documentation PRs to Chainguard Academy. Maybe you found a typo or an outdated instruction in one of our tutorials? Send a PR. Just be aware that some of those docs are automated and shouldn't be manually altered. When in doubt, create an issue first so that we can discuss.

Sending PRs to Chainguard Projects

In order to get your PRs passing CI scripts to Chainguard repositories, your commits must be signed with either Gitsign or with regular gpg signing.

Don't forget to mention the issue ID you're fixing with your PR. For Wolfi PRs, a good title could be something like "Fixing wolfi-bot update: package-name #1234" where 1234 is the number of your assigned issue. For Chainguard Images PRs, we recommend using a [Docs] prefix so that the documentation team can be assigned more quickly to review your PR.

Wolfi Swag

We value all contributors and to show our gratitude, we’ll be giving away a limited number of Wolfi swag packs. If your PR gets accepted, you may be eligible to receive one! Reviewers will leave instructions for you in the eligible PR.

If you still have any questions, don't hesitate to open an issue on the relevant repository or reach out directly on social: https://twitter.com/chainguard_dev .

Happy hacking!

How to Install and Set Up Terminator + Oh My ZSH! on Ubuntu 23.04

Erika Heidi — Tue, 23 May 2023 17:56:20 +0000

I've been a fan and loyal user of Oh-my-Zsh! for many years; it makes my shell more useful with little things such as git branch information and smart autocomplete.

For terminal software, I really enjoy using Terminator, because it allows me to spawn several tiled terminals in a single window, with a custom arrangement that can expand and shrink easily.

The combination of Terminator + Oh My ZSH for me is perfect to improve my productivity since it allows me to see more information instantly and organize terminal windows into tiles with a couple clicks.

In this guide, I'll share in detail how I set up my Terminator with Oh My ZSH and the Powerlevel10k theme.

Step 1: Install Terminator

To get started, install Terminator with:

sudo apt install terminator

When the installation is finished, hit the window key and type terminator to open Terminator from the Ubuntu desktop. It will look like this:

Let's configure it so it looks nicer. Right-click on the terminal window and open "Preferences" on the menu. Go to the "Profiles" tab to customize the default profile.
Later on you can create multiple profiles changing terminal font size and colors, so for instance you can have a "screen" profile for when you need to present content in your terminal.

On the "General" tab, uncheck "Show titlebar":

Then, go to the "Background" tab and set transparent background with a shade of 0.80:

After the change, close the preferences window. Your Terminator should now look similar to this:

To create tiled windows, right-click on the terminal window and select "split horizontally" or "split vertically":

Each new window can be split again, so you have infinite ways to customize the tiles:

For quick access, pin it to your Dock:

hover the mouse to the bottom of the screen to open Dock;
right-click the Terminator icon;
select "Pin to Dash" to pin it to the Dock.

Step 2: Install Oh-My-Zsh!

First install the dependencies zsh and fonts-powerline to support icons in your terminal:

sudo apt install zsh fonts-powerline

Now you can run download and execute the Oh-my-Zsh installation script.

sh -c "$(curl -fsSL https://raw.githubusercontent.com/ohmyzsh/ohmyzsh/master/tools/install.sh)"

The installation will prompt you to confirm that you want to use zsh as default bash. Confirm to continue. When it finishes, you should get a screen similar to this:

You'll need to restart Terminator in order to load the ZSH shell with OMZ.

Step 3: Customize Oh-my-ZSH!

OMZ has several themes that you can install to better customize your terminal, showing useful information based on plugins. Some themes may need additional steps to run properly, such as setting special fonts that support icons or installing dependencies.

To choose a theme, you can have a look at OMZ Themes Section and also the external themes section from their Wiki to choose a theme that you like.

Here are some nice themes to give a try:

Agnoster - A real nice theme that comes built-in, so you don't need to install any extras.
Jonathan - Another built-in theme that adds useful information to the prompt, with a more minimalist look and feel.
AgnosterZak - Based on Agnoster, this theme packs more info into your prompt such as battery life and date/time.
Powerlevel10k - Useful theme that shows lots of info in the terminal and has different color themes. This is the theme that I am currently using.

I personally have been using the Agnoster theme for years, but decided to try something a bit more resourceful and the Powerlevel10k theme offers a lot of extras, and it's super easy to configure with their built-in wizard. This is how my terminal looks like now:

For the built-in themes, you just need to edit your .zshrc and change the ZSH_THEME env var to the name of the theme you want to use. Check the wiki page to see if the theme has special configuration options.

Installing the Powerlevel10k Theme (Optional)

The theme I chose for my new setup is the Powerlevel10k Theme - it's an external theme that requires installation and setup via a friendly CLI wizard tool. Follow these instructions if you want to try it out.

First, install their recommended font. Download the following font files:

Then, go to your Downloads folder, double-click each font and click on the "Install" button to get the font installed to your system.

With the fonts installed, you'll need to update your Terminator profile to use the new font. Right-click on the Terminator window, then access "Preferences" on the menu, and access the "Profiles" tab. With the default profile selected, uncheck the option that says "Use the system fixed width font". Then click on the font select box and choose MesloLGS NF Regular font. You may want to increase the font size, while you're at it. Close the window when you're finished and Terminator should now be using the recommended font for Powerlevel10k.

Next, install Powerlevel10k by cloning it into your OMZ themes folder:

git clone --depth=1 https://github.com/romkatv/powerlevel10k.git ${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/themes/powerlevel10k

Finally, edit your ~/.zshrc and change your ZSH_THEME to powerlevel10k/powerlevel10k:

#~/.zshrc

ZSH_THEME="powerlevel10k/powerlevel10k"

After that, close and open again Terminator to load the new theme. The first time you run OMZ with the Powerlevel10k theme, a CLI wizard script will guide you through the prompt configuration. You can choose from a wide variety of options and styles, it's very intuitive.

It's worth noting that you can run this configuration wizard again at any time to reconfigure your prompt:

p10k configure

After you're satisfied with your initial prompt setup, there's a few more settings you can change by editing your ~/.p10k.zsh file. This config file has a long list of prompt elements that you can enable and disable, so make sure to check it out and uncomment what you'd like to test.

For instance, I enabled the PHP-related elements, so when I open a git-based PHP project I see the PHP version currently set up within the system:

Don't forget to close and re-open Terminator to source the changes you made to the ~/.p10k.zsh file.

I hope you have enjoyed this guide - let me know on Twitter which Oh My ZSH! theme is your favorite!

Update: the fine folks from Oh My ZSH shared a coupon for 10% discount at their merch store, if you love the project consider getting some stickers for support ☺️ Here's the code: 10viaERIKA

Initial Desktop Setup Guide for Ubuntu 23.04

Erika Heidi — Tue, 23 May 2023 16:38:58 +0000

The new Ubuntu 23.04 "Lunar Lobster" was released in late April with some nice updates, most notably the new graphic installer and Gnome 44. If you are migrating from another system or just wants to update to a fresh Ubuntu install, now is a good time to go for it! Even though this release is not an LTS (long-term support) release, it brings many bugfixes and updated software, so it's definitely worth updating if you can.

In this guide, I'll share in detail how I set up a freshly installed Ubuntu 23.04 system to get it ready for work and fun.

Before Starting

If you haven't yet, now is the time to back up your home folder and install Ubuntu 23.04. For a detailed step-by-step guide on how to install Ubuntu 23.04, check my previous post:

How to Install Ubuntu 23.04 on a Desktop or VM

Erika Heidi ・ May 16 '23

#ubuntu #beginners #linux

Once you have your base Ubuntu 23.04 system up and running, you can proceed with the rest of this guide.

1. Installing Updates

As soon as you log in, you'll be asked to install some updates to the system.

You should do that promptly to make sure you get all the latest patches. Proceed when the updates are finished - you may need to restart the computer depending on the type of update.

2. Customizing Appearance

After installing updates, the very first thing I like to do in a fresh new Ubuntu install is customizing the desktop appearance. I don't like the default menu bar on the left, so that's one of the first things I change.

Hit the "window" key to open the desktop search, then type "appearance" to open the settings app where you can select the desktop colors. I personally prefer the light theme, with purple accents. In that screen you can also change your desktop background.

After selecting the theme, color accent, and background, go to the "Ubuntu Desktop" menu that is right below the "Appearance" item on the left menu. In this screen you can change the dock and desktop icons. Here are the settings I use:

Desktop Icons
- Size: large
- Position of new icons: bottom right
- Show personal folder enabled
Dock
- Auto-hide the dock enabled
- Panel mode disabled
- Icon size set to max size
- Position on screen: bottom

On the "Configure dock behavior" menu, I prefer to uncheck the option "Show Volumes and Devices", so my Dock doesn't get too crowded.

Now you should have a nice dock at the bottom of your screen, where you can pin your most used applications:

3. Restoring Backup

Now is a good time to restore backup files, including SSH keys. You may copy the whole home folder back, but if you're like me and likes to start fresh with the minimal amount of things possible, you may prefer to copy folders separately while keeping the full backup in your external drive, in case you need the files later.

Restoring SSH Keys

First thing is to copy your SSH keys. Let's say you copied your home folder to a backups folder in an external device mounted at /media/user/external-disk. The following command will copy the .ssh folder from the backup folder in the external drive and into your home folder. Make sure to replace the drive location with the correct path for your setup.



cp -R /media/user/external-disk/backups/user/.ssh ~/.ssh

You'll most likely need to fix the file permissions for your SSH keys. Here is a summary of how the permissions should look like for your .ssh folder:

Private keys (typically id_rsa, but can have a different name): 0600
Public keys (.pub): 0644
known_hosts and authorized_keys: 0644

To set the permissions:



cd ~/.ssh
chmod 0600 id_rsa
chmod 0644 *.pub
chmod 0644 known_hosts authoeized_keys

Testing Connection to GitHub

After changing the permissions, check that you're able to connect to GitHub using your backed up keys by running the following command:



ssh -T git@github.com

You should get a message like this, informing your username and letting you know that you were able to authenticate successfully:



Hi erikaheidi! You've successfully authenticated, but GitHub does not provide shell access.

Your SSH keys are restored and good to go. While you're at it, configure your git name and email:



git config --global user.email "you@example.com"
git config --global user.name "Your Name"

Restoring other Files

You can follow the same procedure to copy over other folders in your backup, or you can use Nautilus (the file explorer) to copy files using a graphic interface.

4. Installing Essentials

Next, let's install some essential command-line software. The good thing about installing a new distro as soon as it comes out is that the software from official repositories is typically up-to-date with the most recent releases.

Update the apt cache just to be sure:



sudo apt update

The following command will install git, curl, vim, ffmpeg, and docker on your new Ubuntu system:



sudo apt install git curl vim ffmpeg docker

Check also the "Ubuntu Software" Store for more software that you can install directly with a few clicks. This includes software from Snap repositories and also traditional Ubuntu deb repositories.

Some of my personal recommendations:

Inkscape - Vector art, digital illustration
Gimp - Image editing
MyPaint - Digital Drawing
Steam - Gaming on Linux
OpenShot - Video editing
FreeCAD - 3D Design (CAD style)
OBS Studio - Livestreaming and video recording software
Audacity - Audio recording and editing

In the next post of this series about Ubuntu 23.04, we'll install and set up Terminator with Oh-My-ZSH for a pretty and extra customizable terminal prompt.

DEV Community: Erika Heidi

Working with Git Branches and Pull Requests

Git Branches Overview

The Pull Request Workflow

Creating your First Pull Request

Reviewing a Pull Request

Merging a Pull Request

Updating your Local Repository

Sending PRs to Other People’s Projects

Appendix: Merge Conflicts and Common Mistakes

Merge Conflicts

Common mistakes when working with Git

Conclusion

Working with GitHub Repositories

Creating a New SSH Key

Adding an SSH Key to your GitHub Account

Cloning a GitHub Repository

Committing and Pushing your Changes

Creating new Repositories and Connecting Existing Repositories to GitHub

Conclusion

Creating and Customizing your GitHub Profile

Creating a GitHub Account

Customizing your Profile

Creating a README to Further Customize your Profile

Conclusion

An Introduction to Version Control and Git

Overview

Installing and Configuring Git

The Basic Git Workflow

Creating your First Git Repository

Conclusion

Running WordPress on Containers

Migrating to Container-Based Environments

Choosing a WordPress Base Image

CVEs Explained

Scanning WordPress Images for CVEs with Grype

Resources to Learn More

Conclusion

Migrating to Chainguard Images: less CVEs for safer container runtimes

Less CVEs for safer container runtimes

Resources to Learn More

Setting Up Obsidian for Content Planning and Project Management

1. Installing Obsidian

2. Customizing Obsidian Appearance

3. Installing Templater and Tasks plugins

Templater

Tasks

Final Considerations

Creating an Automated Documentation Pipeline in PHP with Autodocs and GitHub Actions

1. Bootstrapping the Demo App

2. Configuring Autodocs Options

3. Registering the Autodocs Service

4. Creating a Build Command

Building the Docs

5. Creating Documentation Pages

5.1 Reference Pages

5.1 Creating a ReadmePage

5.2 Setting up the profile.json Data Source

5.3 Setting Up the readme.tpl Template

5.4 Registering the ReadmePage within Autodocs Configuration

5.5 Building the ReadmePage

6. Running the Demo with GitHub Actions (Optional)

Final Considerations

Development Environments with Docker

Pulling Images from a Registry

Running Containers

Running Containers in Interactive Mode

Running Ephemeral Containers

Checking Container Status

Using Volume Shares

Use Case and Example

Purging Docker Resources

Resources to Learn More

Bonus: Docker Cheat Sheet

Get Involved with Chainguard Projects for Hacktoberfest 2023

Contributing to Wolfi

Identifying Broken PRs

What we expect from contributions

Contributing to Chainguard Images

What we expect from contributions:

5.1 Creating a `ReadmePage`

5.2 Setting up the `profile.json` Data Source

5.3 Setting Up the `readme.tpl` Template

5.4 Registering the `ReadmePage` within Autodocs Configuration

5.5 Building the `ReadmePage`