d3strukt0r/fhnw-artworks-api-php repository overview

⁠fhnw-artworks

The ArtWorks software created by FHNW students.

Project

master-branch (alias stable, latest)

⁠Getting Started

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes. See deployment for notes on how to deploy the project on a live system.

⁠Prerequisites

What things you need to install the software and how to install them

Development requires Vagrant or you can also work with Docker and Docker Compose (You can also install PHP, Composer, Node.js and Yarn)

Production requires either Docker (and optionally Docker Compose) or PHP and Nginx (or any other HTTP server like Apache)

⁠Installing

You can download Vagrant here⁠

You can download Docker from here:

• Windows⁠
• OS X⁠
• Linux⁠

You can download PHP for Windows here⁠ (We recommend "VC15 x64 Thread Safe"). After downloading unpack it anywhere you want. To follow standards you can put it in "C:\Program Files". After that download Composer here⁠. Run the installer. It shouls automatically find the path to PHP, otherwise just do it yourself. Also make sure to add PHP to path.

To figure out how to use PHP and Nginx please refer to Google, as the this would tremendously increase the README.

You can download Node.js here⁠ and Yarn here⁠ (TLDR: npm install -g yarn)

Clone the project to your desired location.

git clone https://github.com/D3strukt0r/fhnw-artworks.git
cd ./fhnw-artworks

If you use Docker and Docker Compose, there is already a docker-compose.yml file shipped, for development. So you can simply run:

docker-compose up

This will build and start the images. You can shut down Docker with CTRL + C.

You still need to setup the development server with mock data. To do that enter the running container with another terminal and run the migration tool:

docker-compose exec php /bin/bash
php artisan migrate:fresh --seed

In case you don't have Docker and want to use Vagrant, do the following steps after having cloned the project.

Enter the api directory

cd api

And download all dependencies with:

composer install

Copy the .env.example to .env and run following commands to create all keys and secrets:

php artisan key:generate
php artisan jwt:secret

Also make sure the database is setup in the .env file as follows:

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=homestead
DB_USERNAME=homestead
DB_PASSWORD=secret

Copy the Homestead.dist.yaml to Homestead.yaml and edit the project path to whereever you saved this project on your computer:

folders:
  # Change the "map" path
  - map: 'C:\<path to folder>\fhnw-artworks\api'
    to: /home/vagrant/code
    type: nfs

To be able to access the homestead site, you also need to add an entry to the hosts file. On Windows it's located at C:\Windows\System32\drivers\etc\hosts, and on macOS and Linux at /etc/hosts. Add following line:

192.168.10.10 homestead.test

If you have more system resources available, consider increasing them in here as well:

# How much RAM to assign to the VM
memory: 2048

# How many cores to assign to the VM
cpus: 2

If running on windows, please install the winnfsd plugin with:

vagrant plugin install vagrant-winnfsd

Start Vagrant with:

vagrant up

Enter Vagrant with:

vagrant ssh

And add seed data to the database by running:

# "cd" to where the code is stored inside Vagrant
cd code
php artisan migrate:fresh --seed

If you want to debug the code, you'll need XDebug. To install it, run the following command inside vagrant and remember where it was installed (eg. zend_extension="/usr/lib/php/20190902/xdebug.so"):

sudo pecl install xdebug

And follow the guide available here⁠. When sending a request via Postman you can simply add ?XDEBUG_SESSION_START=PHPSTORM to the end of the URL.

The client has to be started separately with:

cd ../client
yarn install
yarn run serve

⁠Running the tests

The client uses NPM and Yarn. Therfore first enter the directory:

cd client

Make sure all dependencies are installed:

yarn install

Currently there is test system set up, but if there were, run:

yarn run test

The client uses PHP, Composer and PhpUnit. There first enter the directory:

cd api

Make sure all dependencies are installed:

composer install

Laravel then needs the .env file. Create a copy of .env.example called .env. Then create a random key:

cp .env.example .env
php artisan key:generate

To run the tests, run:

./vendor/bin/phpunit

⁠Deployment

Deployment works with Docker Compose. On the server create a docker-compose.yml file and enter following code for the most minimal setup:

version: "2"

services:
  db:
    image: mariadb
    command:
      - --character-set-server=utf8mb4
      - --collation-server=utf8mb4_unicode_ci
    networks:
      - internal
    volumes:
      - ./database:/var/lib/mysql
    environment:
      MYSQL_ROOT_PASSWORD: password
      MYSQL_DATABASE: artworks

  phpmyadmin:
    image: phpmyadmin/phpmyadmin
    depends_on:
      - db
    networks:
      - internal
    dns:
      - 1.1.1.1
      - 1.0.0.1
    ports:
      - 82:80
    environment:
      UPLOAD_LIMIT: 100M

  php:
    image: d3strukt0r/fhnw-artworks-api-php:latest
    depends_on:
      - db
    networks:
      - internal
    dns:
      - 1.1.1.1
      - 1.0.0.1
    environment:
      DB_HOST: db
      DB_USERNAME: root
      DB_PASSWORD: password
      DB_DATABASE: artworks
      # Create key with "php artisan key:generate"
      APP_KEY: ""
      APP_URL: "http://localhost:81"
      # Create secret with "php artisan jwt:secret"
      JWT_SECRET: ""

  api:
    image: d3strukt0r/fhnw-artworks-api-nginx:latest
    depends_on:
      - php
    networks:
      - internal
    ports:
      - 81:80

  client:
    image: d3strukt0r/fhnw-artworks-client:latest
    depends_on:
      - php
    networks:
      - internal
    ports:
      - 80:80

networks:
  internal:
    external: false

Then start the server in the background:

docker-compose up -d

And to stop it:

docker-compose down

⁠Usage of Docker images

⁠Container Parameters

docker run \
    -e DB_HOST="db" \
    -e DB_USERNAME="root" \
    -e DB_PASSWORD="password" \
    -e DB_DATABASE="artworks" \
    -e APP_KEY="!changeme!" \
    -e APP_URL="http://localhost:81" \
    -e JWT_SECRET="!changeme!" \
    d3strukt0r/fhnw-artworks-api-php

docker run \
    -p 80:80 \
    d3strukt0r/fhnw-artworks-api-nginx

docker run \
    -p 80:80 \
    d3strukt0r/fhnw-artworks-client

⁠Environment Variables

⁠PHP Envs

⁠Entrypoint settings

• ENTRYPOINT_FIX_PERMISSIONS - Fill fix the file permissions in /app (Default: false)

⁠PHP settings

• PHP_MAX_EXECUTION_TIME - The maximum time php can run per request (Default: 100M)
• PHP_MEMORY_LIMIT - The memory limit that php can use (Default: 256M)
• PHP_POST_MAX_SIZE - The maximum size for sending POST requests (maximum upload size) (has to be the same on nginx) (Default: 100M)
• PHP_UPLOAD_MAX_FILESIZE - The maximum size per file for uploading (Default: 100M)

⁠Database settings

• DB_CONNECTION - The database driver that will be used (mysql or pgsql) (Default: mysql)
• DB_HOST - The database server name or IP address (Default: db)
• DB_PORT - The port to connect to the database with (Default: 3306 (mysql) or 5432 (pgsql))
• DB_DATABASE - The name of the database to select (Default: craft)
• DB_USERNAME - The database username to connect with (Default: root)
• DB_PASSWORD - The database password to connect with (Default: )

⁠Laravel settings

• APP_ENV - The environment the app is currently running in (production, testing, local) (Default: production)
• APP_NAME - (Default: Laravel)
• APP_KEY - (Default: ``)
• APP_DEBUG - (Default: false)
• APP_URL - (Default: http://localhost)
• JWT_SECRET - (Default: ``)
• LOG_CHANNEL - (Default: stack)
• BROADCAST_DRIVER - (Default: log)
• CACHE_DRIVER - (Default: file)
• QUEUE_CONNECTION - (Default: sync)
• SESSION_DRIVER - (Default: file)
• SESSION_LIFETIME - (Default: 120)
• REDIS_HOST - (Default: 127.0.0.1)
• REDIS_PASSWORD - (Default: null)
• REDIS_PORT - (Default: 6379)
• MAIL_MAILER - (Default: smtp)
• MAIL_HOST - (Default: smtp.mailtrap.io)
• MAIL_PORT - (Default: 2525)
• MAIL_USERNAME - (Default: null)
• MAIL_PASSWORD - (Default: null)
• MAIL_ENCRYPTION - (Default: null)
• MAIL_FROM_ADDRESS - (Default: null)
• MAIL_FROM_NAME - (Default: ${APP_NAME})
• AWS_ACCESS_KEY_ID - (Default: ``)
• AWS_SECRET_ACCESS_KEY - (Default: ``)
• AWS_DEFAULT_REGION - (Default: us-east-1)
• AWS_BUCKET - (Default: ``)
• PUSHER_APP_ID - (Default: ``)
• PUSHER_APP_KEY - (Default: ``)
• PUSHER_APP_SECRET - (Default: ``)
• PUSHER_APP_CLUSTER - (Default: mt1)
• MIX_PUSHER_APP_KEY - (Default: ${PUSHER_APP_KEY})
• MIX_PUSHER_APP_CLUSTER - (Default: ${PUSHER_APP_CLUSTER})

⁠Nginx Envs

• NGINX_CLIENT_MAX_BODY_SIZE - The maximum size for sending POST requests (maximum upload size) (has to be the same on php) (Default: 100M)
• USE_HTTPS - Enables https. (Not recommeded, rather use Traefik) (Default: false)

⁠Client Envs

• NGINX_CLIENT_MAX_BODY_SIZE - The maximum size for sending POST requests (maximum upload size) (has to be the same on php) (Default: 100M)
• USE_HTTPS - Enables https. (Not recommeded, rather use Traefik) (Default: false)

⁠Volumes

• /app - Where the app is stored

⁠Useful File Locations

⁠PHP Files

• /app/artisan - The artisan command line tool

⁠Built With

• TypeScript⁠ - Programming language
• Yarn⁠ - Dependency management
• Vue.js⁠ - Web framework
• PHP⁠ - Programming language
• Composer⁠ - Dependency management
• Laravel⁠ - PHP framework
• PhpUnit⁠ - Testing utility
• Github Actions⁠ - Automatic CI (Testing) / CD (Deployment)
• Docker⁠ - Containerized image

⁠Contributing

Please read CONTRIBUTING.md⁠ for details on our code of conduct, and the process for submitting pull requests to us.

⁠Versioning

We use SemVer⁠ for versioning. For the versions available, see the tags on this repository⁠.

⁠Authors

• Manuele Vaccari - D3strukt0r⁠ - Initial work
• Victor Hargrave - jokerengine⁠ - TO DO
• Sasa Trajkova - sasatrajkova⁠ - TO DO
• Thomas Weber - tjw52⁠ - TO DO

See also the list of contributors⁠ who participated in this project.

⁠License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE.txt⁠ file for details.

⁠Acknowledgments

• Hat tip to anyone whose code was used
• Inspiration
• etc