Get a backup of your SiteFarm site onto your local machine.
We are going to assume that you already have a SiteFarm site (If you do not, please Request a SiteFarm Site).
Once you have a site, you can log into SiteFactory to manage it.
Once you have logged into SiteFactory you can create a backup of your site. Be sure to check all the boxes to get a complete backup for your local environment.
Preparing to Run the Site Locally
Download a Backup of Your Site
After your site has finished backing up, download it to your machine.
The backup of the site will look something like mywebsite_13253_465463154261253.tag.gz. Go ahead and unzip it. The folder name will be something like mywebsite_13253_465463154261253. Rename it to an appropriate name for your project. For this demo I will be using mywebsite as the example project/site name. I would recommend keeping it to lowercase characters with dashes, and do not put in any empty spaces.
Now you can move this folder anywhere to run the project, but I have run into permission issues when running websites from locations like the Desktop. I would recommend creating a folder in your user folder called websites and relocating the project directory there.
Before building your local environment you will need Docker and Docksal installed on your machine.
Quick Check
If you do any additional web development you may already have Docker and Docksal installed, so if you are not sure, let's do a quick check.
Run docker -v from a command line and you should get a version number.
If you get a command not found error, you likely do not have Docker installed. If you do, you can run the following command to check if Docksal is installed.
Run fin -v from a command line and you should get a version number.
If you have Docker, but get a command not found error for Docksal, jump down to the section "Install Docksal".
You may also find that one or both of these programs are out of date with the latest version. We recommend keeping them updated to the latest version of each to ensure proper functionality.
The best way to update Docker is to open Docker Desktop, go to the Settings (gear icon), and navigate to the Software Updates tab. You can see if there are updates and make them from here.
Note: Docker must be running to update Docksal.
Docksal can be updated by running fin update.
Install Docker
Docker is a container management tool that has replaced the need for virtual machines.
- Download appropriate download for your machine
- Run the .dmg file and drag and drop Docker to Applications
- Choose “Recommended settings”
- Sign up or into Docker Desktop account
- Open Docker Desktop
Once you have Docker installed you can install Docksal.
Install Docksal
Docksal is a web development environment for Docker that helps us manage projects like SiteFarm locally. You must have Docker installed first.
Install Docksal for Docker on Mac OSX
After installing Docker Desktop open a terminal window and run the following command DOCKER_NATIVE=1 bash <(curl -fsSL https://get.docksal.io)
If you run into errors you may need to restart Docker due to recent configuration.
You should now have Docker and Docksal installed and ready to use. You can double check Docker is installed by running docker info in a terminal window, and Docksal by running fin --version.
Now that we have our prerequisite technology we can start our project.
Starting Your Project
Build a Local Environment Using Docker and Docksal
Open a terminal window and navigate to your project folder. If you place it where I recommended earlier, then cd ~/websites should get you into the correct directory. Then navigate one level deeper into your project, cd mywebsite (replacing mywebsite with the name of your folder/site/project). Make sure that the Docker Desktop application is open and currently running.
If you just installed Docker and Docksal I recommend closing and restarting both of those programs before running the next command. I also suggest stopping any other containers that you may have running in Docker so as to prevent any port conflicts.
Start Docker in the Docker Desktop app.
Run fin themer/init from inside your website directory. This should kickoff the project build. It may ask for an administrative password during this process so stay near by while it is doing its thing.
Upon completion it should provide you with a local link to view your website. Open this in a browser and you should see a working version of your website.
Troubleshooting: If your project build throws some errors and fails to build your local site successfully I recommend running the fin project remove command. Say yes to the prompt, and then I would restart Docker Desktop, and attempt the fin themer/init command again.
Docksal Commands
- Get all the Docksal commands and help
fin fin upstarts docker and the project containerfin startstarts up the project containerfin stopstops running the docker container
The only custom commands listed when you run fin that you should be using are fin themer/init the first time you create your project, and fin themer/refresh when you want to rebuild the database from the database.sql file in the root of your site project. This is covered in more detail on the Update Code and Files for Local Development page.