Installation

You have 2 options to install Qore:

• Follow steps manually
• Use the Qore CLI

Both options will end up with the same result, but the manual installation will give you more insight/understanding of the setup.

Manual Installation

Installation

Start by opening your terminal and cloning the Skeleton repository:

git clone git@gitlab.qlic.nl:qore/skeleton-v2.git myproject

Back-end setup

Go to the directory and clone .env.example to .env:

cd myproject
cp .env.example .env

Now because we're having qore/system as a composer package we need to install it. However, this package exists only in our Gitlab environment, so we need to add a auth.json in the root of the project:

touch auth.json

Inside this file, put a Gitlab token. You can generate this in your Gitlab profile.

{"gitlab-token":{"gitlab.qlic.nl":"glpat-mytokenxxxx"}}

Now run composer install:

composer install

There is a big chance you will run into the problem that ext-imagick is not installed for PHP. You can either install it on your system, use docker or just ignore it for now as it is only used for image manipulation:

composer install --ignore-platform-reqs

To set up the database, you can either use your local MySQL setup, or use Docker.

Database setup via Docker

Open your docker-composer.yml, comment everything except the mysql service, and configure as needed:

version: "3.8"

services:
    mysql:
        build:
            context: docker/mysql

        container_name: myproject

        environment:
            MYSQL_USER: myproject
            MYSQL_PASSWORD: password
            MYSQL_DATABASE: myproject_db
            MYSQL_ROOT_PASSWORD: password
            MYSQL_ALLOW_EMPTY_PASSWORD: "false"

        volumes:
            - .:/database

        ports:
            - "3306:3306"

Make sure to update your .env (should probably keep DB_USERNAME as root) and compose the Docker container:

docker compose up -d

Now finish up the installation:

php artisan vendor:publish --tag=qore.system.db # This will publish the latest qore migrations
composer fresh # This will migrate and seed the database
php artisan key:generate
php artisan storage:link
git remote remove origin # Remove the origin remote (which is set to skeleton at this point)

Front-end setup

The next step is to install the front-end. The Qore front-end (at this time of writing) does not exist as a package, so we need to clone it:

cd frontend/src
git clone git@gitlab.qlic.nl:qore/qore-frontend.git qore
cd ../ # Back to frontend directory
cp .env.example .env # Copy the .env.example to .env
yarn # If you run into node version problems, you can use nvm to switch to the correct version (e.g. nvm use 18)

Installation via Qore CLI

You can instantiate a new Qore project via the qore-cli tool.

Prerequisite

• Docker 3.8
• Node >= 14.0 & Yarn

Installation

Start by installing the qore-cli tool with yarn global.

To do this you have to modify your .npmrc file to permit installs from GitLab Package Manager .

In short do the following steps:

1. Retrieve your token

• Head over to GitLab Personal Access Token
• Create new token with the scopes at least api,read_api,read_repository

2. Update .npmrc

npm config set @qore:registry https://gitlab.qlic.nl/api/v4/packages/npm/
npm config set '//gitlab.qlic.nl/api/v4/packages/npm/:_authToken' "<token>"

3. In case it doesn't work just with that, you need to add the CLI to .npmrc too:

npm config set '//gitlab.qlic.nl/api/v4/projects/301/packages/npm/:_authToken' "<token>"

4. Now we can install the CLI:

yarn global add @qore/cli

5. Now to create a project run:

qore create

danger

Composer packages are not installed by the create command. (will be installed in next step)

Finishing the setup

The application is close to being ready to be run. We need a few more steps. You can choose to either run the application via Docker, or via php artisan serve.

Tip: You can also choose to use Docker only for the database by editing the docker-composer.yml and commenting everything except the mysql service, and running: docker compose up

Running via Artisan serve

Setup

Install composer packages:

composer install

Migrating and Seeding

In order to seed migrate and seed the database:

caution

Make sure you have the latest qore/system migrations by running: php artisan vendor:publish --tag=qore.system.db

composer fresh

The composer.json comes with a composer fresh command, this will migrate and seed your database:

php artisan migrate:fresh --seed
php artisan tenants:migrate
php artisan tenants:seed

Serving your app

Link storage:

php artisan storage:link

Running the app:

php artisan serve

Running via Docker

Setup

Start the application:

./basket start:detached

Install composer packages:

./basket run composer i

Link storage:

./basket run php artisan storage:link --relative

Rebuild the NGiNX container:

./basket stop
./basket start:detached --build

Interacting with containers

info

To connect to different docker containers you need to update the host for each one corresponding.

For example for mysql you need to update the .env DB_HOST.

DB_CONNECTION=mysql
- DB_HOST=127.0.0.1
+ DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=skeleton_db
DB_USERNAME=root
DB_PASSWORD=password

Migrating and Seeding

In order to seed migrate and seed the database, you may use the run helper:

caution

Make sure you have the latest qore/system migrations by running: php artisan vendor:publish --tag=qore.system.db

./basket run composer fresh

The composer.json comes with a composer fresh command, this will migrate and seed your database:

php artisan migrate:fresh --seed
php artisan tenants:migrate
php artisan tenants:seed

Serving your app

We have made some docker helpers to ease starting and stopping the application.

The following commands are available:

• ./basket start - Start docker containers
• ./basket start:detached - Start docker containers, detached
• ./basket stop - Stop the docker containers
• ./basket down - Kill the docker containers (removes the storage)
• ./basket mysql - Enter the MySQL database container
• ./basket run - Run commands inside the PHP container (eg: ./basket php artisan migrate)

caution

Make sure you have filled your root .env and root/frontend .env with the right variables

For serving your application run:

./basket start:detached

Running the Front-end

Navigate in a terminal to /frontend in your project directory. Then, run:

yarn dev

success

Everything should be done now! You can use the default account to log in admin@qlic.nl with password.