For newer developers
For newer developers, detailed instructions for setting up a development environment
Initial setup
If you already have a code repository using the BaseCMS Website Framework, feel free to use your own repository to follow along with this guide. We'll be using an example code repository as we work through the concepts in this guide. Feel free to fork this repo, or use your own to follow along!
Development environment
In order to develop with the BaseCMS Website Framework effectively, you'll need a local development environment that allows you to make your modifications efficiently, with the security of knowing that your code will work every step of the way from your machine to the production environment.
However, you're more than welcome to use any tool or utility you're more familiar with! For a list of alternatives, see the tools & utilities section.
Git
We use Git (and GitHub for hosting). Git is a distributed version control system which retains a history of file modifications very efficiently. We'll use the GitHub Desktop GUI and the git CLI utility in these examples. For installation instructions, see the git client section.
Docker (and Docker Compose)
In order to ensure consistency, we use Docker Compose to define our development environment (and a Dockerfile to define the production environment.) All examples within this guide will use these utilities to install and run the code repository. For installation instructions, see the containerization section.
Editor
We love Visual Studio Code! We'll be using it in our examples, but feel free to use your own IDE if you're more comfortable with it. For installation instructions, see the code editor section.
Getting your code
The next two sections will describe how to use GitHub and Git to fork (create your own copy of) and clone (download) the example repository. If you already have your own website repository, you can clone that instead, and if you already have your code ready for use, feel free to jump ahead to running your code.
Creating a fork
When browsing any code repository (that supports it) on GitHub, you'll see a Fork button at the top. If you click on this button, you can make your own copy of the code and change it however you like! Press the Fork button at the top of the example repository to create your own copy to use in this guide.
If you belong to one or more organizations on GitHub, you'll be prompted to select where to fork your code repository to. If you do, you likely know where you want to save it already, but if not: select your user account!
Cloning (it's not just for sheep!)
Once you have access to a copy of the code, you can clone it to your local machine. Also called checking out, this simply means downloading the code to your computer.
If you prefer the git CLI, you can run the following command to check out your code:
If you prefer the GUI, you can clone your repository within GitHub Desktop by selecting it under the Your repositories tab, and then clicking on the Clone button.
If you chose not to create a GitHub account but installed GitHub Desktop, you can use the Clone a Repository from the internet option:
Running your code
Now that your code is checked out, only a few steps remain: Setting up your IDE, installing dependencies, and booting it up.
Setting up your IDE
Conveniently, GitHub Desktop has a direct integration with VSCode! To open the IDE to your project, select the Open in Visual Studio Code button on the repository view:
If you're not sure where your code was checked out to, check within your Git client. In GitHub Desktop, selecting the repository will display additional information about the repo, including the option to open a Finder/Explorer window.
Installing dependencies
One major advantage of VSCode is the integrated terminal, which you'll need to use to start and stop your website. You can use any terminal you wish for this purpose, but we'll show examples within VSCode.
Open a terminal window in VSCode using the shortcut Ctrl+` or the Terminal > New Terminal menu. To install your project's dependencies, run the following command:
If your project doesn't have a scripts/yarn.sh file, run the following command:
If you're using a non-dockerized development environment, free free to just run yarn here.
Starting your site
Once your dependencies are installed, you're ready to boot up the website framework. To do so, run the following command:
If you don't know the service name to use, check the docker-compose.yml file at the root of your project. There should be a key under the services: section related to your website -- use that here. In the example repository, the service name is example.com.
Accessing your website
When the build is complete, you will see a message like the following, indicating the hostname (0.0.0.0) and port (4008) where you can access your website.
You can Cmd+Click (Ctrl+Click on Windows) to open the URL in your default browser:
Troubleshooting
The dependency installation and initial boot are two areas that can be very prone to errors, mostly due to differences in configuration or installed software. While we use Docker to ensure a unified runtime environment for the code, differences in configuration can cause problems for first time setup. If you're unable to complete these sections successfully, check out the troubleshooting guide for common solutions to startup errors.
Putting it all together
Now that you've set up your development environment and can access your website on your machine, it's time for the fun to begin! The next steps are to make modifications to your code, contribute, and publish the changes.
Last updated
