Quick Start

Local Development

Find the code here (opens in a new tab).

Dependencies

Before you begin local development, ensure that the following dependencies are installed:

Local Development Setup

Get the code

You have two options to get started with GhostRemix: using the template or forking the repository. Here's when to use each approach:

Using the Template

Use the template when:

  • You want to create a private repository (GitHub doesn't allow forking directly to a private repo).
  • You don't plan to contribute back to the original project.
  • You want a clean start without the original project's commit history.

To use the template:

  1. Navigate to the GhostRemix repository (opens in a new tab).
  2. Click the "Use this template" button.
  3. Choose a name for your new repository and select whether it should be public or private.
  4. Click "Create repository from template".

Alternatively, you can use the GitHub CLI:

gh repo create your-new-repo --template mikan-laboratory/ghost-remix --private
cd your-new-repo
git push --set-upstream origin main

Forking the Repository

Fork the repository when:

  • You want to contribute back to the original project.
  • You want to keep up with updates to the original project.
  • You're okay with a public repository (you can make it private later, but it starts as public).

To fork the repository:

  1. Navigate to the GhostRemix repository (opens in a new tab).
  2. Click the "Fork" button in the top-right corner.
  3. Choose where to fork the repository (your personal account or an organization).
  4. Optionally, you can change the name of the forked repository.
  5. Click "Create fork".

After forking, clone your forked repository:

git clone https://github.com/your-username/ghost-remix.git
cd ghost-remix

To keep your fork up to date with the original repository:

  1. Add the original repository as an upstream remote:

    git remote add upstream https://github.com/mikan-laboratory/ghost-remix.git

  2. Fetch the latest changes from the upstream repository:

    git fetch upstream

  3. Merge the changes into your local main branch:

    git checkout main
git merge upstream/main

  4. Push the updated main branch to your fork:

    git push origin main

Remember, if you make changes you want to contribute back to the original project, create a new branch for your changes and submit a pull request from that branch.

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.

  1. Create Mailgun (opens in a new tab) account.

  2. Navigate to Sending -> Domains. You should see a test domain that looks like sandbox1234567890abcdef1234567890ab.mailgun.org

  3. Add your email as an authorized recipient.

  4. Scroll down and select API Keys. Create a new API key and copy the key.

  5. 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

RapidRead

FeaturesDeployment