Setting up a local development environment on Windows
This article provides instructions for setting up your Windows computer to allow you to work on J&E client sites locally. The process is slightly more involved on Windows than it is on macOS or Linux because most of the underlying technologies that make up a local development environment are tailored for Linux and its derivatives, but Windows does offer a familiar graphical user interface alternative to the command line for those users who would prefer this option.
There are two approaches discussed here: the graphical (GUI) approach and the command-line (CLI) approach. Most Windows users are more familiar with graphical user interfaces, but the command line is available for more advanced users or those who would prefer a more streamlined workflow. It also shares many commands and principals with the command line setups of macOS and Linux.
Note: You should only need to set up your local development environment once, unless you make significant changes to your computer (i.e. you upgrade your major version of Windows) or you begin working on a new computer.
To perform the steps in this article, you'll need:
- a capable computer running Microsoft Windows 10 or later;
- at least 8 GB of RAM;
- a high-speed Internet connection;
- at least 100 MB of available disk space, plus about 500 MB of additional space for each Website you plan to work on;
- Git for Windows (see below for installation instructions);
- Valet for Windows (see below for installation instructions);
- MariaDB 10.5 or later (see below for installation instructions)
- and a user account with administrator rights or the password to an account with administrator rights.
Note: You may be able to run a local development environment without administrator access to your computer, but this setup process has not been tested and is not encouraged.
Installing Git for Windows
Git for Windows is a collection of tools and utilities that allows Git, a version control system built for Linux, to run on the Windows operating system. It is the first step of the development environment setup process because it is required for cloning and managing Website repositories, and is needed regardless of whether you use graphical or command-line tools to manage those repositories. To install Git for Windows, do the following:
- Download the latest release of Git for Windows from the official Website and save the setup file to a location on your computer.
- Double-click the file you downloaded to launch the Git for Windows installer. If you're prompted for an administrator password or confirmation, type the password or provide confirmation.
- Read the license agreement that appears, then click Next to indicate your acceptance of the agreement.
- If you are happy with the default location where Git for Windows will be installed, click Next, otherwise click Browse to select a different location.
- The default set of installable features shown on the next screen are enough to run your local development environment, but if you want any additional features installed, select them and then click Next.
- If you are happy with the name of the Start Menu folder where Git for Windows icons will be placed, click Next, otherwise type in a different folder name.
- Select the text editor you would like to use with Git, and then click Next.
- On the next screen, select "Override the default branch name for new repositories," type "master" into the text box, and then click Next.
- Click Next on each of the seven additional screens that appear to accept the default options, or customize them as desired, then click Install to begin the installation process.
Installing Valet for Windows
One of the best things about working on Websites locally is the ability to preview your changes before pushing them to the Website's staging or production environments. This allows you to make fewer commits because you can ensure your changes are as you intended before committing them to the repository.
The software that facilitates these previews is called Valet. Originally designed to run on macOS, it was ported to Windows and is available as open source software. Valet makes previewing local Websites convenient by setting up a Web server on your Windows machine, automatically mapping site folders to DNS domains, and automatically managing PHP and related dependencies that WordPress and other programs need.
To install Valet for Windows, please do the following:
- Use the search box in the task bar or on the Start menu to find the PowerShell application, right-click on it, and select "Run as Administrator." If you're prompted for an administrator password or confirmation, type the password or provide confirmation.
- Type the commands below, exactly as shown, and then press the Enter key. This will install the latest version of PHP on your computer.
# PHP 7.4 Set-ExecutionPolicy RemoteSigned; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.SecurityProtocolType]::Tls12; Invoke-WebRequest -Uri "https://github.com/cretueusebiu/valet-windows/raw/master/bin/php74.ps1" -OutFile $env:temp\php74.ps1; .$env:temp\php74.ps1
- Once the installation completes, close the PowerShell window.
- Download the Composer Installer and save the file to a location on your computer. This program will install Composer, a package management utility needed to install Valet Windows and its related components.
- Double-click the file you downloaded to start the installer, then select the option to install Composer for all users of the computer. If you're prompted for an administrator password or confirmation, type the password or provide confirmation.
- On the next screen, keep the "Developer mode" checkbox unchecked and click Next.
- Check to make sure that the version of PHP recognized by Composer is the one you just installed via PowerShell (see steps 1 and 2), and then click Next.
- If you use a proxy server to connect to the Internet, check the "Use a proxy server to connect to Internet" box and then click Next.
- Click Install if you are happy with the installation settings shown on your screen, and then wait while your computer downloads and installs the Composer files.
- Once Composer has been installed, open a Command Prompt window by searching for it on the Start menu, right-clicking the app, and selecting "Run as Administrator." If you're prompted for an administrator password or confirmation, type the password or provide confirmation.
- Run this command to install Valet for Windows using the Composer package manager:
composer global require cretueusebiu/valet-windows
- Next, run the
valet installcommand. This will configure and install Valet and register Valet's daemon to launch when your system starts.
- Decide on the location where all of your Website repositories will be stored. Create this folder inside File Explorer and make note of its path.
- Return to the Command Prompt, and change directories to the folder you just created. To do this, run the following command, replacing the "C:\websites" path with your own:
- Finally, run the
valet parkcommand to tell Valet to use this path to find your Websites. Once the path has been "parked," all of the subfolders inside that path will be available in your Web browser at an address like
folderis a subfolder inside the path you chose.
Many of the Websites you will develop for J&E Media will be powered by dynamic applications that store their data in a relational database. The most popular of these is MySQL and its superior fork, MariaDB. To install MariaDB on your computer for your local sites to use, do the following:
- Download the latest stable release of MariaDB for Windows and save the file to a location on your computer.
- Double-click the setup file to launch the MariaDB installer, then click Next on the welcome screen.
- Check the box to indicate your acceptance of the license agreement, then click Next.
- If you want to add, remove, or customize the MariaDB features that will be installed, make your selections and then click Next. At a minimum, you will need to ensure the "MariaDB Server" and "Client Programs" features are selected for installation.
- Uncheck the "Modify password for database user
root" checkbox to leave the root user password empty, and then click Next. On a production database server, this would be a grave security risk, but local installations of MariaDB refuse connections over the network by default, ensuring that your local machine is the only machine that can access this MariaDB installation.
- Leave all of the settings on the next screen at their defaults unless you have been told by J&E system administration staff to specifically change them, and then click Next.
- Click the Install button to begin installing MariaDB on your computer. If you're prompted for an administrator password or confirmation, type the password or provide confirmation.
- Click the Finish button once the installation has finished to exit the setup program.
The GUI approach
This approach will guide you through installing and setting up graphical user interfaces to manage local Website repositories. It is best for Windows users who would prefer graphical environments, or who are unfamiliar with Git or the command line.
Step 1: Install SourceTree
SourceTree is one of the most popular Git version control tools on Windows; it's also available for macOS as well. It will be the central location where all of your repository management happens, including cloning, pulling down changes, and pushing your own changes. To install SourceTree, do the following:
- Download the latest release of SourceTree for Windows from the official SourceTree Website and save the setup file to a location on your computer.
- Double-click the file you downloaded to launch the SourceTree installer.
- When it opens, you may be prompted to create a BitBucket Cloud account, but since J&E uses our own internal repository hosting and collaboration software, this is not necessary. Click Skip to continue.
- On the next screen, uncheck the Git installation option since you installed Git in the previous section, then click Next to begin the installation.
- Once SourceTree has been installed, you will be asked to enter your name and e-mail address. These details will be associated with every change you commit to Websites you work on. Enter your full first and last name and your J&E company e-mail address, and then click Next to close the installer.
Note: SourceTree is not the only graphical user interface for managing Git repositories on Windows, but it is the official interface recommended by J&E Media Corp.
Step 2: Configure SourceTree and SSH authentication
Now that SourceTree has been installed, you can configure it to work with the J&E Collaboration Platform, which is our internal repository hosting and collaboration software.
Internal note from Logan: this is where my contributions end for the GUI approach as SourceTree is not an accessible application. I trust that someone else from the development team will be able to fill in the rest of the setup and configuration steps.
The CLI approach
This approach uses the command line to set up and configure your local development environment. It assumes you have basic familiarity with command line concepts and will use the command line to manage your local repositories, rather than a graphical user interface.
The simplicity of the command line can best be illustrated by the fact that only one step is required to get ready for managing Website repositories on your local computer: creating and adding an SSH key pair.
An SSH key pair consists of a public and private key that is used in place of a username and password when authenticating to the J&E Collaboration Platform. Authentication is required for actions such as cloning a repository, pushing your repository changes to the server, and more. Setting up an SSH key pair ensures that you will always be able to authenticate without ever being prompted for your credentials.
To begin, create a folder named
.ssh in your local user folder. The best way to do this is by right-clicking on an empty area of your local user folder, clicking New, and then clicking Folder. Name the folder
Next, open the folder and create a new file inside named
config. Place the following into this file:
host git.jemcdev.com HostName git.jemcdev.com IdentityFile ~/.ssh/id_rsa User gitmanager
Finally, create your SSH key pair and configure your J&E Collaboration Platform account to use the pair by performing the following steps:
- Open a Git Bash terminal by selecting the Git Bash item in your Start menu.
- Run the following command to create the SSH key pair, and press the Enter key for each of the questions you are asked:
ssh-keygen -b 4096 -N "" -t rsa
- Open the
.sshfolder you created earlier and make sure the public and private key files have been created there.
- Open the public key, typically named
id_rsa.pub, found in this folder, in your favorite text editor, and copy the contents to your clipboard.
- Open your favorite Web browser and go to the SSH keys page of your J&E Collaboration Platform user account settings.
- Click the "Add Key" link in the "Manage SSH Keys" section.
- In the "Key name" field, enter a descriptive name you can use to refer to this key in the future. This is useful if you have multiple computers and want to give a unique display name to each computer's key.
- Paste the contents of your public key into the "Content" field, and then click the "Add" button to add the key to your user account.
And that's it, you've successfully set up your Windows command-line environment to work with Website repositories. For more information about cloning, pushing to, pulling from, and managing these repositories, please see the Managing a Local Git Repository knowledge base article.