1. Initial Setup

This guide will walk you through setting up your local development environment for working on KZ client sites.

By the end of this guide, you will have a fully functional local WordPress site that mirrors our staging environment.

2. Required Software Installation

Before starting, install the following applications.

2.1 Local by Flywheel

Local is a free local WordPress development tool.

• Download from: https://localwp.com/
• Available for both Mac and PC

2.2 Visual Studio Code

VS Code is our primary code editor.

• Download from: https://code.visualstudio.com/
• Available for both Mac and PC

2.3 GitHub Desktop

GitHub Desktop provides a GUI for Git operations.

• Download from: https://desktop.github.com/download/
• Available for both Mac and PC

Note: Install all three applications before proceeding to the next section.

3. Creating Your Local Site

3.1 Understanding Our Repository Structure

Before creating a site, familiarize yourself with our GitHub organization.

Each site has two repositories:

• Main repo: Contains themes, index.php, and must-use plugins.
• Plugins repo: Contains all plugin-specific changes. These are usually named with a -plugins suffix.

Repository authors show team members who have contributed code.

3.2 Creating the Site in Local

Step 1: Initial Setup

1. Click Add Local Site.
2. Select Create a new site.
3. Enter the site name.
4. Click Advanced options.
5. Change .local to .test in the domain name.
6. Set the site path to a folder called Local Sites.

Important: Always use .test domains for consistency across the team.

Step 2: Environment Configuration

You need to match the staging site’s environment as closely as possible.

Finding the Correct PHP Version

1. Navigate to the staging site.Example: docs.kzstage.com/wp-admin
2. Log in with the zeitguys username.
3. Go to Tools → Site Health.
4. Click the Info tab.
5. Expand the Server dropdown.
6. Note the PHP version.

PHP Version Selection

• PHP uses semantic versioning: MAJOR.MINOR.PATCH
• Example: If staging shows PHP 8.3.30, selecting PHP 8.3.23 in Local is acceptable.
• Minor differences in patch versions are usually okay.
• If unsure, consult a senior developer.

Other Environment Settings

• Web Server: nginx 1.26.1, or the latest available version.
• Database: Most recent MySQL version, such as MySQL 8.0.35.

Step 3: WordPress Setup

Use these standard credentials:

• Username: Kobayashi
• Password: Zeitguys

Multisite Configuration

Some sites use WordPress Multisite for multilingual content.

Examples:

• Subdirectory: example.com/en/home, example.com/fr/home
• Subdomain: en.example.com/home, fr.example.com/home

Most sites are not multisites. Select No unless specified.

To complete the setup:

1. Leave email and language as default.
2. Click Add Site.
3. Enter your computer admin password when prompted.

3.3 SSL Certificate Configuration

Trusting the SSL Certificate on Mac

1. In Local, go to the site’s Overview tab.
2. Click Trust next to the SSL row.
3. Open the Keychain Access application.
4. Search for your site name.Example: howhub
5. Double-click the certificate.
6. Expand the Trust section.
7. Set When using this certificate to Always Trust.
8. Close the window and enter your password.

3.4 Converting to HTTPS

By default, Local creates HTTP sites. We need to convert the site to HTTPS.

1. Go to the Database tab in Local.
2. Click Open AdminNeo in the Connect row.
3. In AdminNeo, locate and open the wp_options table.
4. Click Select Data at the top.
5. Edit the following rows:

• option_id 2 / siteurl: Change http://sitename.test to https://sitename.test
• option_id 3 / home: Change http://sitename.test to https://sitename.test

6. Click save for each change.

Troubleshooting note: If /wp-admin redirects incorrectly and adds a port number, this is a known issue. Verify that your SSL and HTTPS settings are correct.

4. Cloning Repositories

4.1 Understanding the File Structure

WordPress sites have this structure:

• app/public — Web root where WordPress core lives.
• app/public/wp-admin — WordPress admin files.
• app/public/wp-includes — WordPress core libraries.
• app/public/wp-content — Custom themes, plugins, uploads, and the main area we work in.

4.2 Preparing the wp-content Directory

1. Navigate to your site folder.

You can do this by:

• Clicking Open Site Folder in Local.
• Or manually navigating to:

Local Sites/sitename/app/public

2. Delete the existing wp-content folder.
3. Create a new empty folder named wp-content.

Why? Git cannot clone into a non-empty directory. We replace the default wp-content folder with our repository.

4.3 Cloning the Main Repository

Using Terminal

1. Navigate to GitHub and find your site’s repository.

Example:

https://github.com/Kobayashi-Zeitguys/howhub

2. Click the green Code button.
3. Copy the SSH link.

Example:

git@github.com:Kobayashi-Zeitguys/howhub.git

4. Open Terminal and navigate to the empty wp-content folder.

Example:

cd /Users/username/Local Sites/sitename/app/public/wp-content/

5. Clone the repository.

git clone git@github.com:Kobayashi-Zeitguys/howhub.git .

Critical: Notice the trailing period at the end of the clone command. This tells Git to clone into the current directory instead of creating a new subfolder.

Without the period:

• wp-content/howhub/{files}
• Incorrect

With the period:

• wp-content/{files}
• Correct

4.4 Cloning the Plugins Repository

1. Create a plugins folder inside wp-content.

mkdir /Users/username/Local Sites/sitename/app/public/wp-content/plugins

2. Navigate to the plugins folder.

cd /Users/username/Local Sites/sitename/app/public/wp-content/plugins

3. Find the plugins repository on GitHub.

Example:

https://github.com/Kobayashi-Zeitguys/howhub-plugins

4. Copy the SSH URL and clone the repo.

git clone git@github.com:Kobayashi-Zeitguys/howhub-plugins.git .

Remember: Include the trailing period here as well.

4.5 Verification

After cloning both repositories, your file structure should look like this:

wp-content/

• themes/
• plugins/
  • plugin-name-1/
  • plugin-name-2/
• index.php

5. Migrating Staging Content

We use the All-In-One WP Migration plugin to copy the database and content from staging to local.

---

5.1 Installing the Migration Plugin

Check if the plugin is already in your plugins repository.

• If it is present, simply activate it in WordPress admin.
• If it is not present, install it manually.

Manual Installation

1. Go to your local site’s admin dashboard.

Example:

https://sitename.test/wp-admin

2. Navigate to Plugins → Add Plugin.
3. Search for All-In-One WP Migration.
4. Install the plugin by ServMask.
5. Click Activate.

5.2 Exporting from Staging

1. Log into the staging site’s admin panel.

Example:

docs.kzstage.com/wp-admin

2. Install and activate All-In-One WP Migration if it is not already active.
3. Navigate to All-In-One WP Migration → Export.
4. Click Advanced options.
5. Configure the export settings.

Set compression to:

• None

This is important for large sites.

Include everything except the following:

• Do not encrypt this backup with a password.
• Do not exclude the database.
• Do not exclude selected database tables.
• Do not exclude selected files.

6. Click Export Site To → File.
7. Wait for the download to complete.

---

5.3 Importing to Local

1. On your local site, go to All-In-One WP Migration → Import.
2. Click Import From → File.
3. Select the file you downloaded from staging.
4. Review the warning message carefully.

Before proceeding, verify:

• You are importing the correct file.
• You are on the correct local site.

5. Click Proceed.

Warning: This will completely replace your local database. Double-check that you are importing to the correct site. If you accidentally import to the wrong site without a backup, you could lose everything.

After the import is successful, your local site will be an exact copy of staging, minus the media library. The media library is added in the next step.

6. Media Library Setup

The migration plugin excludes the uploads folder to keep file sizes manageable. We manually download and transfer the media library.

---

6.1 Understanding Hosting Boxes

Our sites are distributed across several hosting servers.

• Host1: Live production sites.
• Host2: Additional live production sites.
• DevCow: All staging sites.
• Internal: Internal and live sites.

6.2 Accessing cPanel

1. Log into WHM for the appropriate box.

For staging sites, use WHM Internal.

2. Search for or scroll to List Accounts.
3. Find your site in the account list.

Example:

docs.kzstage.com

4. Click the cP icon to open cPanel for that specific site.

Understanding cPanel vs WHM

• cPanel: Manages a single site, including files, emails, databases, and domains.
• WHM: Admin panel for managing multiple cPanel accounts and server settings.

6.3 Downloading the Media Library

1. In cPanel, search for or find File Manager.
2. Navigate to public_html → wp-content.
3. Locate the uploads folder.
4. Right-click the uploads folder and select Compress.
5. Choose a compression format, such as tar or zip.
6. Wait for compression to complete.
7. Close the log and refresh the directory.
8. Download the compressed file.

6.4 Installing the Media Library Locally

1. Extract or unzip the downloaded file on your computer.
2. Navigate to your local site’s uploads folder.

Local Sites/sitename/app/public/wp-content/uploads

3. Delete the existing uploads folder.
4. Replace it with the extracted uploads folder from staging.
5. Refresh your local site.

All media should now display correctly.

7. Making Code Changes

7.1 Opening the Project in VS Code

1. In Local, click the VS Code button on your site’s dashboard.
2. VS Code will open with the site’s codebase.
3. All development work should be done in the wp-content folder.

Important: Only modify files within wp-content, as this is the Git repository. Changes outside this folder will not be tracked.

7.2 Tracking Changes

As you make changes:

• Modified files will automatically appear in GitHub Desktop.
• You can review all changes before committing.
• GitHub Desktop shows line-by-line differences.

8. Git Workflow and Deployment

8.1 Commit Naming Convention

We follow a specific format for commit messages.

Format:

[branch-name] – [commit message]

Examples:

• feature/faq-block – Added styling to FAQ content title
• fix/header-menu – Corrected mobile menu alignment
• update/homepage – Updated hero section copy

8.2 Committing Changes

1. Review your changes in GitHub Desktop.
2. Enter a commit message following the naming convention.
3. Click Commit to [branch-name].
4. Click Push origin to push to GitHub.

8.3 Creating a Pull Request

If you are working on a feature branch, create a pull request.

Option 1: Using the Quick Link

This is the recommended method.

1. After pushing, GitHub often displays a yellow banner on the repository homepage.
2. Click Compare & pull request.

Option 2: Manual Creation

1. Go to your repository on GitHub.

Example:

https://github.com/Kobayashi-Zeitguys/howhub/pulls

2. Click New pull request.
3. Set the base branch.

This is usually master or development.

4. Set the compare branch.

Example:

base: master ← compare: feature/faq-block

5. Review the changes.
6. Click Create pull request.
7. Add a description if needed.
8. Submit the pull request for review.

8.4 Merging the Pull Request

1. GitHub will check for merge conflicts.
2. If no conflicts exist, you will see Ready to merge.
3. Click Merge pull request.
4. Confirm the merge.
5. Optionally delete the feature branch after merging.

8.5 Deploying to Staging

After merging, pull the changes to the staging server.

1. Access cPanel for the staging site.
2. Open Terminal in cPanel.
3. Navigate to the wp-content directory.

cd public_html/wp-content/

4. Pull the latest changes.

git pull

5. When prompted for a password, enter:

Kobayashi

6. Verify the changes were pulled successfully.

The terminal will show which files were updated and the commit messages.

9. Terminal Reference

This section shows what successful terminal commands should look like.

9.1 Cloning the Main Repository

Example command:

git clone git@github.com:Kobayashi-Zeitguys/howhub.git .

Example successful output:

Cloning into '.'...

remote: Enumerating objects: 2135, done.

remote: Counting objects: 100% (2135/2135), done.

remote: Compressing objects: 100% (1329/1329), done.

remote: Total 2135 (delta 890), reused 2009 (delta 764), pack-reused 0

Receiving objects: 100% (2135/2135), 15.35 MiB | 22.75 MiB/s, done.

Resolving deltas: 100% (890/890), done.

9.2 Cloning the Plugins Repository

Example command:

git clone git@github.com:Kobayashi-Zeitguys/howhub-plugins.git .

Example successful output:

Cloning into '.'...

remote: Enumerating objects: 11880, done.

remote: Counting objects: 100% (11880/11880), done.

remote: Compressing objects: 100% (6162/6162), done.

remote: Total 11880 (delta 4765), reused 11873 (delta 4758), pack-reused 0

Receiving objects: 100% (11880), 22.80 MiB | 29.26 MiB/s, done.

Resolving deltas: 100% (4765), done.

These outputs confirm successful cloning. The numbers may vary depending on repository size.

Conclusion

You now have a complete local development environment that mirrors our staging sites.

You can make changes locally, test them thoroughly, and deploy them through our Git workflow.

Best Practices

• Always test changes locally before committing.
• Use descriptive commit messages following our naming convention.
• Create feature branches for new work.
• Pull from staging regularly to stay up to date.
• Ask senior developers when unsure about any step.

Getting Help

If you encounter issues during setup:

• Check each step carefully. Most issues come from missed steps.
• Verify file paths and directory structures.
• Ensure you are using the correct credentials.
• Ask senior team members for assistance when needed.

Welcome to the team! Happy coding!