Skip to content

Instantly share code, notes, and snippets.

@nitsan-technologies

nitsan-technologies/hubspot-docker-ddev.txt

Last active April 3, 2025 06:18
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save nitsan-technologies/6ee0d534714cb984d2290ad830e33d22 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save nitsan-technologies/6ee0d534714cb984d2290ad830e33d22 to your computer and use it in GitHub Desktop.
Download ZIP
HubSpot CMS Local Installation with Docker/DDEV
Raw
hubspot-docker-ddev.txt
Setting up a local development environment for HubSpot CMS has often been a challenge, especially for those who prefer modern tools like Docker and DDEV. When our team encountered this problem, we realized that no straightforward solution was readily available. After rigorous testing and troubleshooting, we’ve created this guide to help others avoid the hurdles we faced. This setup will not only simplify your workflow but also empower you to leverage the full potential of HubSpot CMS for seamless website development.
---
## **Why Use Docker and DDEV for HubSpot CMS Local Development?**
* **Consistency:** With Docker, you can create a standardized environment that works across different systems.
* **Simplified Workflow:** DDEV eliminates the need for manual configurations and ensures smooth integration with Docker for HubSpot CMS.
* **Speed:** Both tools together drastically reduce setup time, allowing you to focus on development tasks.
* **Flexibility:** Easily switch between projects and manage dependencies without affecting your local machine.
Docker and DDEV bring immense value to HubSpot CMS developers, making the development process more efficient and collaborative.
---
## **Prerequisites**
Before starting, ensure you have the following installed on your system:
* **Docker:** Install Docker by following the official [Docker installation guide](https://www.docker.com/get-started).
* **DDEV:** Install DDEV by referring to the [DDEV installation guide](https://ddev.readthedocs.io/en/stable/#installation).
### **Step 1: Install Docker for Local Development**
1. Visit [Docker’s website](https://www.docker.com/products/docker-desktop) and download Docker Desktop for your operating system.
2. Follow the installation instructions specific to your OS.
3. Verify the installation by running the following command:
**docker \--version**
### **Step 2: Install DDEV for HubSpot CMS Projects**
1. Install DDEV using Homebrew (Mac/Linux) or Chocolatey (Windows) as per the official documentation.
2. Verify the installation by running:
**ddev \--version**
---
## **Step-by-Step Guide for HubSpot CMS Local Development Setup**
### **Step 1: Set Up a HubSpot Developer Account for Local Development**
1. Go to the [HubSpot Developer Portal](https://developers.hubspot.com/).
2. Sign up for a developer account or log in if you already have one.
### **Step 2: Create a HubSpot CMS Sandbox Account**
1. Log in to your HubSpot developer account.
2. Navigate to **Accounts** \> **Create Sandbox**.
3. Follow the prompts to create a sandbox account for development and testing.
For more details, visit the official [HubSpot CMS Developer Sandbox page](https://offers.hubspot.com/free-cms-developer-sandbox).
---
### **Step 3: Configure DDEV for HubSpot CMS**
1. Navigate to your project directory in the terminal:
2. Run the following command to initialize a new DDEV project with PHP as the project type:
**ddev config**
3. When prompted:
* Set the project type to **PHP**.
* Configure the project settings as needed.
---
### **Step 4: Modify the Dockerfile for HubSpot CLI Support**
1. Open the .ddev/web-build/Dockerfile file in your project directory.
2. Uncomment all the lines in the Dockerfile to activate them.
3. Add the following line at the end of the file:
**RUN npm install \-g @hubspot/cli**
This ensures that the HubSpot CLI is installed in your local environment.
---
### **Step 5: Start DDEV Environment**
1. Start the DDEV container by running:
**ddev start**
2. Ensure the environment is running properly.
---
### **Step 6: Install HubSpot CLI Inside DDEV**
1. Execute the following command to install the latest version of the HubSpot CLI inside the container:
**ddev exec npm install \-g @hubspot/cli@latest**
---
### **Step 7: Initialize Your HubSpot Project**
1. Run the following command to initialize your HubSpot project:
**ddev exec hs init**
2. Follow the prompts to authenticate and link your project to your HubSpot account.
---
### **Step 8: Create a Website Theme Using HubSpot CLI**
1. Use the HubSpot CLI to create a default boilerplate theme:
**ddev exec hs create website-theme my-website-theme**
---
### **Step 9: Upload Your Theme to HubSpot CMS**
1. Upload the newly created theme to your HubSpot account:
**ddev exec hs upload my-website-theme my-website-theme**
---
### **Step 10: Create a Website Page in HubSpot CMS**
1. Log in to your HubSpot account.
2. Navigate to **Content** \> **Website**.
3. Use the uploaded theme to create a new website page.
---
### **Step 11: Watch for Theme Changes with HubSpot CLI**
1. Use the following command to enable live watch mode for the theme:
**ddev exec hs watch my-website-theme my-website-theme**
2. This will automatically upload changes to HubSpot as you edit files locally.
---
### **Step 12: Start Developing Your HubSpot Theme**
1. Begin editing the files in the my-website-theme directory.
2. Test your changes locally, and they’ll sync to HubSpot in real-time.
---
### **Step 13: Finalize and Upload the Updated Theme**
1. Once development is complete, re-upload the updated theme to HubSpot:
**ddev exec hs upload my-website-theme my-website-theme**
---
## **Conclusion**
When our team first tried setting up HubSpot CMS with Docker and DDEV, we struggled to find clear documentation. After overcoming these challenges, we realized the immense benefits this setup offers:
* **Faster Development Cycles**: Reduced setup time and easy switching between projects.
* **Consistent Environments**: No more "it works on my machine" issues.
* **Streamlined HubSpot Integration**: Seamless theme and module development.
We hope this guide saves you the trouble we experienced and empowers you to leverage HubSpot CMS to its fullest potential. If you have any questions or run into issues, don’t hesitate to reach out. Happy coding\!
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment