Skip to main content

Local Development

This document describes how to set up a local development environment for working with Geekle. After following this guide, you should be able to run individual parts or the entirety of the Geekle application locally.

Prerequisites​

  • A pre-existing deployment of Geekle.
  • Nodeblocks NPM token with read permissions on @basaldev packages.
  • Node.js 18.x or later.
  • (Recommended) VSCode

Set your NPM token​

NODEBLOCKS_DEV_TOKEN is required to install private packages. Set NODEBLOCKS_DEV_TOKEN in your local environment before proceeding.

Add the following to your shell profile (e.g. ~/.bashrc, ~/.zshrc, etc.):

export NODEBLOCKS_DEV_TOKEN=__INSERT_YOUR_TOKEN_HERE__

Connecting to MongoDB​

Geekle uses MongoDB Atlas as its main database store. For local development of back-end services, while it is possible to use a local MongoDB instance, it is recommended to use MongoDB Atlas to ensure that:

  • The local development environment is as close as possible to the production environment.
  • Any features that require MongoDB Atlas-specific features are tested correctly.
  • Indexes and other database configurations are consistent between local and production environments.

To connect to MongoDB Atlas:

  1. First either create a new cluster or use an existing one.
  2. Then, create a new database user with permission to read and write to the database.
  3. (Optional) Whitelist your IP address to allow connections from your local machine.
  4. Get the connection string for your MongoDB Atlas cluster. This can be found in the MongoDB Atlas dashboard under the "Connect" tab for your cluster. Use the username and password you created in step 2 to connect to the database.

Now that you have a connection string, you can use it to connect to MongoDB Atlas from your local services for testing.

Running back-end services locally​

For each back-end service (geekle-xxx-service), you can run the service locally by following these steps:

  1. Clone the repository for the service you want to run.

  2. Install the dependencies:

npm install

  1. Create a .env file for the service from the default .env.example file.

  2. Update the .env file with the required configuration values as taken from Nodeblocks Cloud. If you need access to these values, the easiest method is to access Google App Engine and view the environment variables for the currently deployed services. This is available under the 'Versions' tab for the service.

  3. For MongoDB Atlas, set the DATABASE_URL environment variable to the connection string you obtained earlier.

  4. Run the service:

npm run build
npm run start
warning

For local development, it is easiest to run a single service locally, and then connect it to the deployed services on Nodeblocks Cloud. This allows you to develop the service in isolation from the rest of the Geekle application.

However, requests that are intended for this service from other services will not succeed unless you also run the other services locally. For efficiency, plan ahead and only run the services you need for the feature you are developing.

Making edits​

Use VSCode or your preferred editor to make changes to the service. We do not provide a editor config for back-end ser ices.

Running tests​

Back-end services have unit tests that can be run locally. To run the tests:

npm run test

We recommend writing tests for any new features or customizations you make to the Geekle application.

Release your changes​

Create a PR with your changes to the Geekle repository. Once the PR is merged, you can redeploy the appropriate service in Nodeblocks Cloud when ready. Nodeblocks Cloud has a branch parameter, which will configure which branch will be used for the deployment. This allows you to test a experiemental branch before mergine the PR.

Running the Front-end locally​

For each front-end service (geekle-frontend-xxx), you can run the app locally by following these steps:

  1. Clone the repository for the app you want to run.

  2. Install the dependencies (Note that we use yarn for the front-end services):

nvm use
yarn
  1. Create a self-signed SSL certificate for local development:

This assumes a Mac environment. For other environments, please refer to the appropriate documentation for your operating system for creating a self-signed SSL certificate.

brew install mkcert
mkcert -install
mkcert localhost
  1. Ensure that these certs are not committed to the repository by adding them to the .gitignore file:
echo "localhost-key.pem" >> .gitignore
echo "localhost.pem" >> .gitignore
  1. Open the repository in VSCode using the editor config provided:
code .vscode/geekle-frontend-xxx.code-workspace
  1. Configure your local development vite.config.ts file to point to the correct back-end services and use your certificate:
import fs from 'fs';

const safeLoadFile = (path: string) => {
  if (fs.existsSync(path)) {
    return fs.readFileSync(path, 'utf8');
  }
  return undefined;
};

export default (defineConfig as typeof testConfig)({
  ...

  server: {
    https: {
      key: safeLoadFile('./localhost-key.pem'),
      cert: safeLoadFile('./localhost.pem'),
    },
    open: '/',
    proxy: {
      '/api/demand-auth': {
        target: 'https://<service-url-here>',
        changeOrigin: true,
        rewrite: (path) => path.replace(/^\/api\/demand-auth/, ''),
      },
      ...
    },
  },
});

Ensure that you specify an entry in the proxy object for each back-end service that this app needs to connect to. Check the .gcloud/router-service/server.js file (the routing service) to see which services are available.

  1. Run the app:
yarn dev

The app should automatically open in your default browser.

If you want to specify an alternate URL for a backend service, you can do so using the vite.config.ts file proxy changes as above.

Making edits​

Use VSCode to make changes to the app. We provide an editor config for the front-end services, which should pick up on any typescript issues you may have.

Running storybook​

Run storybook via the following command:

yarn storybook

This will open a new browser window with the storybook UI, which you can use to view and test the components in the front-end service.

Release your changes​

Create a PR with your changes to the Geekle repository. Front-end services have a CI/CD pipeline that will check your PR for any issues before merging.

After merging to main, your changes will automatically be deployed to App Engine. You can view the deployment status in the Google Cloud Console or Github Actions.