Skip to content

Latest commit

 

History

History
117 lines (74 loc) · 5.55 KB

blog-scenario.md

File metadata and controls

117 lines (74 loc) · 5.55 KB
Raw

This document will guide you through the prerequisites and commands necessary to setup and preview the portal project, locally on your computer.

Prerequisites

  • VS Code
    • You can use any other editor of choice but this guide will assume you are using VS Code
  • VS Code Dev Containers
    • This will allow you to run the project in a containerized environment

Project Structure

Within the packages folder, you will find the two projects that make up this scenario:

  • blog-cms - The Strapi CMS
  • blog - The Next.js frontend

Local Development

Note: This scenario has been optimised for use with VS Code Remote Containers, and contains definitions to setup the PostgreSQL database that Strapi uses, and this guide makes the assumption that you will use the dev container.

Install the required Node.js packages

The repo is a monorepo, and thus contains all the components from all the scenarios. To support this npm workspaces has been configured, and as a result, all scenarios packages will be installed.

To install all packages required run the following command:

npm install --workspaces

Note: The devcontainer will automatically execute this command on creation, but you can execute it manually if you wish to see the installation happen.

Starting Strapi

Strapi requires environment variables to provide the various JWT secrets. A sample of the .env file can be found at packages/blog-cms/.env.example which contains default values for all the required environment variables. Copy this file to packages/blog-cms/.env:

cp packages/blog-cms/.env.example packages/blog-cms/.env

Note: You don't need to set the PostgreSQL environment variables, as these are set in the dev container definition.

To start the Strapi CMS, run the following command:

npm run develop --workspace blog-cms

Strapi will then be running at http://localhost:1337/admin.

Note: On first run, sample data will be loaded into the database, but you will need to setup an admin user, following the guide on the admin portal.

Starting Next.js

To start the Next.js application, run the following command:

npm run dev --workspace blog

The Next.js application will then be running at http://localhost:3000.

Local development without using the devcontainer

If you do not wish to use the use the devcontainer for local development there are some additional steps that need to be undertaken.

A PostgreSQL database is required by Strapi, so one will need to be provisioned. If you are provisioning a PostgreSQL database on WSL (using Ubuntu), please follow these steps:

  • Update the package list: sudo apt update
  • Install PostgreSQL: sudo apt install postgresql
  • Confirm that PostgreSQL is active and running sudo systemctl status postgresql
  • Confirm that PostgreSQL is accepting connections sudo -u postgres psql

Next, create the database:

  • Switch to the postgres system user account: sudo su - postgres
  • Then access the PostgreSQL shell: psql
  • Create a user for Strapi: CREATE USER strapi WITH PASSWORD 'strapi';
  • Create a database for Strapi: CREATE DATABASE strapi;
  • Grant privileges to the user: GRANT ALL PRIVILEGES ON DATABASE strapi TO strapi;
  • Then quite the PostgreSQL shell: \q
  • Restart the PostgreSQL service: sudo systemctl restart postgresql

Note: If you are using a different system, please follow the PostgreSQL installation guide.

Once the PostgreSQL cluster is up and running and the database is created, the following additional environment variables will need to be provided, either in the .env file or globally:

DATABASE_HOST= <localhost or IP of your PostgreSQL server>
DATABASE_USERNAME=strapi
DATABASE_PASSWORD=strapi
DATABASE_NAME=strapi

Note: The database provided in DATABASE_NAME will need to exist on the server before starting Strapi

Also, please install the following dependencies:

  • Install azd

    • azd is use to provision, manage and deploy the applicaton to Azure. Follow the install guide for your OS
    • Note: azd is not required if you wish to only rely on GitHub Actions or Azure Pipelines to deploy using the provided CI/CD pipelines

  • Install Node.js

    • It is encouraged that a Node.js version manager, such as nvm, is used as a .nvmrc file is provided to specify the version of Node.js that is required

Running in GitHub Codespaces

An alternative way to run the environment is using GitHub Codespaces, which will use the devcontainer definition, but create a remote containerised environment, rather than running the environment locally.

Note: GitHub Codespaces is a paid component of GitHub. Review the GitHub Codespaces billing before using it.

To run in GitHub Codespaces, the machine will need at least 4 CPUs and 8GB of memory, which is defined in the devcontainer.json file, to ensure all the services are started.

Blog scenario diagram

This scenario is represented by the following diagram Contoso Real Estate Blog - Scenario 1