Start Strapi
Clone the Repository to Your Local Machine
# Clone the repository
git clone git@github.com:frameless/strapi.git
# Navigate to the project directory
cd frameless-cms
Prepare the App
Before running the app, make sure you have the following prerequisites installed on your machine:
- Yarn Classic version 1.22.19
- Node.js version 20.10
Follow these steps to prepare the app:
-
Open your terminal and navigate to the root level of the app.
-
Install Dependencies:
yarn install
-
Build the Project:
yarn build
These commands will ensure that all necessary dependencies are installed and the project is built successfully. Once completed, you'll be ready to run the app.
Start the Server using Docker
To run the application as a Docker container on your Mac, follow these steps:
-
Install Docker Desktop:
- Go to the Docker website and download Docker Desktop for Mac.
- Install Docker Desktop by following the installation instructions for macOS.
- Ensure you have
docker-compose
available. For example by installing docker-compose with Homebrew
-
Launch Docker Desktop:
- Once Docker Desktop is installed, launch it from your Applications folder.
-
Add Environments variables to the project
Create two files in the project root:
.project-name.prod.env
and.project-name.dev.env
(replace "project-name" with your specific project name, e.g.,.pdc.prod.env
and.pdc.dev.env
). If these files don't exist already, copy the environment variables provided below into these files. The project file will be copied to.env
when starting said app.ADMIN_JWT_SECRET=someSecretKey== API_TOKEN_SALT=someRandomLongString== APP_KEYS=key1==,key2==,key3==,key4== CSP_CONNECT_SRC_URLS= CSP_FONT_SRC_URLS= CSP_FORM_ACTION_URLS= CSP_FRAME_SRC_URLS= CSP_IMG_SRC_URLS= CSP_SCRIPT_SRC_URLS= CSP_STYLE_SRC_URLS= CSP_WORKER_SRC_URLS= DATABASE_CLIENT=postgres DATABASE_HOST=0.0.0.0 DATABASE_NAME=postgres DATABASE_PASSWORD=strapi DATABASE_PORT=5432 DATABASE_SSL=false DATABASE_USERNAME=postgres FRONTEND_PUBLIC_URL=http://localhost:3000 FRONTEND_PUBLIC_URL=http://localhost:3000 HOST=0.0.0.0 JWT_SECRET=someOtherSecretKey== MATOMO_HOST= MATOMO_SITE_ID= NODE_ENV=development OGONE_PAYMENT_SERVICE_URL= OPEN_FORMS_API_TOKEN= OPEN_FORMS_API_TOKEN= OPEN_FORMS_API_URL=http://localhost:8000/api/v2/ OPEN_FORMS_API_URL=http://localhost:8000/api/v2/ OPEN_FORMS_CSS_URL=http://localhost:8000/static/sdk/open-forms-sdk.css OPEN_FORMS_SDK_URL=http://localhost:8000/static/sdk/open-forms-sdk.js PANDOSEARCH_API_URL= # You can use the following API URL to test the functionality of the SearchBar component: https://public.pandosearch.com/developer.pandosearch.com/. Valid keys that can be used in the searchBar field include: search, server, highlighting, and help. PGADMIN_DEFAULT_EMAIL=admin@admin.com PGADMIN_DEFAULT_PASSWORD=root PORT=1337 PREVIEW_SECRET_TOKEN=someSecretToken== # gained from tribal knowledge STRAPI_ENV_LABEL= STRAPI_PRIVATE_URL=http://pdc_strapi:1337 STRAPI_PUBLIC_URL=http://pdc_strapi:1337 SURVEY_RUN_APIKEY= SURVEY_RUN_GUID= SURVEY_RUN_URL= TRANSFER_TOKEN_SALT=anotherRandomLongString==
-
Run the Docker Image:
Start the environment with the following commands:
# development cd bin/ && bash ./deploy.sh project-name dev up --build # or # example cd bin/ && bash ./deploy.sh pdc-dashboard dev up --build # production cd bin/ && bash ./deploy.sh project-name prod up --build # example cd bin/ && bash ./deploy.sh pdc-dashboard prod up --build
Valid project names are:
pdc-dashboard
vth-dashboard
kennisbank-dashboard
Visit http://localhost:1337/admin to set up an admin account. Afterward, configure the right permissions for unauthenticated users and field labels in Settings > CONFIG SYNC > Interface. Click the Import Button.
Now, you can create products and FAQ items using the Content Manager and view them on the frontend: http://localhost:3000/.
Environments Variables Types
Variable name | Description | Type | Default Value | Application | Note |
---|---|---|---|---|---|
ADMIN_JWT_SECRET | Secret for signing JWTs for the Admin panel | String | strapi-dashboard | Admin panel configuration | |
APP_KEYS | The secret key for session cookie signing | String | strapi-dashboard | Server configuration | |
API_TOKEN_SALT | Salt for generating API tokens | String | strapi-dashboard | Admin panel configuration | |
CSP_CONNECT_SRC_URLS | Space-separated list of URLs to allow in Content-Security-Policy for connect-src | ||||
CSP_FONT_SRC_URLS | Space-separated list of URLs to allow in Content-Security-Policy for font-src | ||||
CSP_FORM_ACTION_URLS | Space-separated list of URLs to allow in Content-Security-Policy for form-action | ||||
CSP_FRAME_SRC_URLS | Space-separated list of URLs to allow in Content-Security-Policy for frame-src | ||||
CSP_IMG_SRC_URLS | Space-separated list of URLs to allow in Content-Security-Policy for img-src | ||||
CSP_SCRIPT_SRC_URLS | Space-separated list of URLs to allow in Content-Security-Policy for script-src | ||||
CSP_STYLE_SRC_URLS | Space-separated list of URLs to allow in Content-Security-Policy for style-src | ||||
CSP_WORKER_SRC_URLS | Space-separated list of URLs to allow in Content-Security-Policy for worker-src | ||||
DATABASE_CLIENT | Database client to use | String | sqlite | strapi-dashboard | Reference to Strapi Database docs |
DATABASE_HOST | Database host | String | strapi-dashboard | Reference to Strapi Database docs | |
DATABASE_NAME | Database name | String | strapi-dashboard | Reference to Strapi Database docs | |
DATABASE_PASSWORD | Database password | String | strapi-dashboard | Reference to Strapi Database docs | |
DATABASE_PORT | Database port | String | strapi-dashboard | Reference to Strapi Database docs | |
DATABASE_SSL | For SSL database connection. Use an object to pass certificate files as strings. | Boolean or Object | strapi-dashboard | Reference to Strapi Database docs | |
DATABASE_USERNAME | Database username | String | strapi-dashboard | Reference to Strapi Database docs | |
FRONTEND_PUBLIC_URL | String | strapi-dashboard | |||
HOST | Number | strapi-dashboard | Admin panel configuration | ||
I18N_DEBUG | When I18N_DEBUG is set, the i18next package will log debug information. | String | frontend | ||
JWT_SECRET | Secret for signing JWTs for the Users-Permissions plugin | String | strapi-dashboard | Admin panel configuration | |
MATOMO_HOST | PDC ONLY / Optional: URL for Matomo | URL | FRONTEND | ||
MATOMO_SITE_ID | PDC ONLY / Optional: container ID for Matomo | String | FRONTEND | ||
NODE_ENV | production | development | ||||
OPEN_FORMS_API_TOKEN | PDC ONLY: A Token for Open Forms API | String | strapi-dashboard / frontend | ||
OPEN_FORMS_API_URL | PDC ONLY: URL for Open Forms API (usually the origin + /api/v2) | String | frontend / strapi-dashboard | ||
OPEN_FORMS_CSS_URL | PDC ONLY / Optional: URL for Open Forms CSS | String | frontend | ||
OPEN_FORMS_SDK_URL | PDC ONLY / Optional : URL for Open Forms SDK | String | frontend | ||
PANDOSEARCH_API_URL | PDC ONLY | String | frontend | ||
PGADMIN_DEFAULT_EMAIL | String | Database | |||
PGADMIN_DEFAULT_PASSWORD | String | Database | |||
PORT | Port on which the server should be running. | Number | 1337 | strapi-dashboard | |
PREVIEW_SECRET_TOKEN | The secret used for the Strapi preview plugin should have the same value for both the frontend and the Strapi dashboard. | String | strapi-dashboard frontend | ||
STRAPI_PRIVATE_URL | String | frontend | |||
STRAPI_PUBLIC_URL | URL | Frontend | The Strapi dashboard URL, e.g.,http://localhost:1337/ | ||
TRANSFER_TOKEN_SALT | Salt for generating Transfer tokens. If no transfer token salt is defined, transfer features will be disabled. | String | strapi-dashboard | Admin panel configuration Secrets can be generated manually by running node -p "require('crypto').randomBytes(48).toString('base64');" | |
OGONE_PAYMENT_SERVICE_URL | PDC ONLY: URL for Open Forms/Payment | URL | Frontend | ||
SURVEY_RUN_GUID | PDC ONLY: Used for the Survey service | String | Fronend | ||
SURVEY_RUN_APIKEY | PDC ONLY: Used for the Survey service | String | Fronend | ||
SURVEY_RUN_URL | PDC ONLY: Used for the Survey service | URL | Fronend |
Start the server without Docker
Before starting the server without Docker, create a .env
file for both the frontend and the Strapi dashboard app.
Frontend env:
FRONTEND_PUBLIC_URL=http://localhost:3000
# these three environments variables below are required to be able to test the openFormsEmbed into the frontend. So you have to start the OpenForms server on your local machine
OPEN_FORMS_API_URL=http://localhost:8000/api/v2/
OPEN_FORMS_CSS_URL=http://localhost:8000/static/sdk/open-forms-sdk.css
OPEN_FORMS_SDK_URL=http://localhost:8000/static/sdk/open-forms-sdk.js
OPEN_FORMS_API_TOKEN=
PANDOSEARCH_API_URL= # You can use the following API URL to test the functionality of the SearchBar component: https://public.pandosearch.com/developer.pandosearch.com/. Valid keys that can be used in the searchBar field include: search, server, highlighting, and help.
PREVIEW_SECRET_TOKEN= # the value should matched the same environment variable on the Strapi dashboard
STRAPI_PRIVATE_URL=http://0.0.0.0:1337/
STRAPI_PUBLIC_URL=http://0.0.0.0:1337/
SURVEY_RUN_APIKEY=
SURVEY_RUN_GUID=
SURVEY_RUN_URL=
Strapi Dashboard env:
NODE_ENV=development
ADMIN_JWT_SECRET=
API_TOKEN_SALT=
APP_KEYS=
FRONTEND_PUBLIC_URL=http://localhost:3000
HOST=0.0.0.0
JWT_SECRET=
OPEN_FORMS_API_TOKEN=
OPEN_FORMS_API_URL=http://localhost:8000/api/v2/
PORT=1337
# the value should matched the same environment variable on the Frontend
PREVIEW_SECRET_TOKEN=
STRAPI_PRIVATE_URL=http://0.0.0.0:1337
STRAPI_PUBLIC_URL=http://0.0.0.0:1337
TRANSFER_TOKEN_SALT=
Two Options to Run the Server
-
Using the Start Script:
-
Navigate to the app's root level and run the following command:
yarn development
-
You will be prompted with options to select. For example:
❯ yarn development yarn run v1.22.19 $ node scripts/start.js ? Select an option: … Build # build a specific app or both ❯ Dev # start a development server for a specific app or both Start # start a production server for a specific app or both
-
Choose the "Dev" option to start a development server for the specified app.
-
-
Basic Way:
-
Change to the app's directory (e.g.,
cd apps/pdc-dashboard
) and run:yarn dev
-
-
Using Yarn Workspaces:
- Run the following command from the project root:
yarn workspace @frameless/pdc-dashboard dev
Choose the option that best fits your workflow to start the server without Docker. Once the server is running, you can access the application from your browser.
FAQ
I Have Issues with Building the Project or Starting the Server
If you encounter problems with building the project or starting the server, try the following steps:
-
Remove Build Folders:
-
Execute the following commands from the app root level:
yarn clean yarn build
-
This will remove the
/build
or/dist
folders and rebuild the entire project.
-
-
Remove Node Modules:
-
If the issue persists, remove the
node_modules
folders for all the apps using the command:npx npkill
-
Afterward, reinstall the dependencies with:
yarn install
-
These steps can help resolve common issues related to project build and server startup. If you continue to face problems, feel free to reach out for further assistance.