Local Development
Find the code here (opens in a new tab).
Dependencies
Before you begin local development, ensure that the following dependencies are installed:
- NPM (opens in a new tab): A package manager for JavaScript, used to install and manage project dependencies.
- Docker (opens in a new tab): A platform for developing, shipping, and running applications in isolated environments (containers).
- Tilt (opens in a new tab): An essential tool for managing microservice development with support for Docker.
Local Development Setup
To set up your local development environment, follow these steps:
Get the code
Use the template to create your own repository.
GitHub UI
- Navigate to the repository (opens in a new tab), click
Use this template
, and follow the instructions.
GitHub CLI
- Get the GitHub CLI (opens in a new tab)
# Step 1: Clone the template repository
git clone https://github.com/mikab-laboratory/ghost-remix.git new-project
cd new-project
# Step 2: Create a new repository on GitHub
gh repo create username/new-project --private --source=.
# Step 3: Push the cloned contents to the new repository
git push --set-upstream origin main
Mailgun
You don't need Mailgun to get started, but you'll need for email-based workflows like member sign up. Don't worry about the $35 a month price tag, immediately after signing up for the trial, you can downgrade to the flex plan.
-
Create Mailgun (opens in a new tab) account.
-
Navigate to Sending -> Domains. You should see a test domain that looks like
sandbox1234567890abcdef1234567890ab.mailgun.org
-
Add your email as an authorized recipient.
-
Scroll down and select API Keys. Create a new API key and copy the key.
-
Find the correct base URL here (opens in a new tab).
Create an env file
You'll need to create a .env file in the project root, using .env.example as a guide.
Start Tilt
This will install dependencies, generate a prisma client, and start all services.
tilt up
Seed
Use the Seed button in the Ghost section of the Tilt UI to populate basic data.
- The production script seeds an owner and basic settings. The development script includes posts and comments.
- If you want to inspect the database, you can manually trigger a GUI from the Tilt UI.
Engine
The Node engine is set to 18.19 in package.json to match the production runtime. This follows the Ghost team's advice. You can find more information here (opens in a new tab).
Using a different version locally shouldn't be an issue, but you will see a warning when you run npm install
. If you want to use this version in development, you can use a tool like nvm (opens in a new tab) to manage multiple Node versions.
Theme
You can change the theme colors in app/theme/theme.ts
.
Favicon
You can replace the favicon.ico with your own in the public folder. If you are using a PNG, you will need to add <link rel="icon" href="/favicon.png" type="image/png" />
to the <head>
component under <Meta/>
in the root.tsx
file. If you are unsure about turning your logo into a favicon, we used favicon.io (opens in a new tab) to do it for free.
Pages
Published pages are automatically added to the menu in the navigation bar.
Test Docker Build
Ensure your Docker build is correctly configured:
Build
Execute the build process:
make all
Cleanup
After testing, clean up the build environment:
make clean-all