Skip to content

Latest commit

 

History

History
executable file
·
245 lines (220 loc) · 9.33 KB

readme.md

File metadata and controls

executable file
·
245 lines (220 loc) · 9.33 KB
Raw

Application documentation

Defeloper: Flag Studio

Services:

  • app
    • Debian base (registry.gitlab.com/flagstudio/laraflag:base)
    • Node 16.13.1
    • PHP: 8.1.5
    • Laravel: 9.10.1
    • Laravel nova: 3.30.0
  • postgres (can be swapped to mysql)
    • dockerhub image
    • Postgres 13.2
  • mysql (can be swapped to postgres)
    • custom image (registry.gitlab.com/flagstudio/laraflag:mysql-8.0-base)
    • MySQL 8.0
  • traefik (only for local development)
    • dockerhub image (traefik:v2.5.6)
    • Traefik 2.5.6
  • redis (laravel cache driver usage)
    • dockerhub image (redis:6.2.5-buster)
    • 6.2.5-buster
  • meilisearch (full text search engine, can be swapped to elasticsearch)
    • dockerhub image (getmeili/meilisearch:v0.24.0)
    • meilisearch v0.24.0
  • elasticsearch (full text search engine, can be swapped to meilisearch)
    • custom image (registry.gitlab.com/flagstudio/laraflag:elasticsearch-7.6.2)
    • elasticsearch-7.6.2
  • mailhog (do not use in production)
    • dockerhub image (mailhog/mailhog)
    • latest

Docker Compose configuration files

  • utility compose files:
    • docker-compose.build-base.yml — Just an utility setup for base image build, used for application base image build for future push to container registry, you can read Build and push base image section
    • docker-compose.build-app.yml — Just an utility setup for application image build, based on base image, used for build and future push to container registry, you can read Build and push app image section
  • environment orchestration compose files:
    • docker-compose.yml — For local development
    • docker-compose.prod.yml — Orchestration setup to run on the production environment. Placed on a production server from master branch, renamed to docker-compose.yml, used by Ansible Deployer
    • docker-compose.test.yml — Orchestration setup to run on the test environment. Placed on a staging server from develop branch, renamed to docker-compose.yml, used by Ansible Deployer
    • docker-compose.prod.yml — Orchestration setup to run on the premaster environment. Placed on a staging server from premaster branch, renamed to docker-compose.yml, used by Ansible Deployer

Configuration files

Common

  • .env — the only configuration is not under VCS, so it stores all the settings of the app and docker
  • docker/app/www.conf — php-fpm settings
  • docker/app/laraflag.ini — php settings
  • docker/app/crontab — cron jobs
  • docker/app/supervisord.conf — supervisor
  • docker/app/opcache.ini — opcache
  • docker/app/xdebug.ini — xdebug

Local

  • docker/app/xdebug.ini — xdebug
  • docker/app/xdebug.bash — xdebug manage bash script

For developers

Build & run project locally

  • Check docker-compose.yml file and change the default key project to env variable <COMPOSE_PROJECT_NAME> value:
...
networks:
project: # <- change this key to COMPOSE_PROJECT_NAME env variable value e.g.: 'mdat' 
driver: overlay
external: true
...
  • Create docker network by bash command:
docker network create <COMPOSE_PROJECT_NAME>
  • Run a bash command
docker-compose up -d
  • Add DNS records to your local hosts file:
    • 127.0.0.1 <APP_URI> <TRAEFIK_URI> <MAILHOG_UI_URI> <MEILISEARCH_URI> <ELASTICSEARCH_URI>
  • !!! ATTENTION !!! All commands in the app container should be executed from non-root user flag, use --user=flag argument for that
  • Go to the shell of app container by bash command: 
    docker-compose exec --user=flag app /bin/bash
    • Run by bash command 
      composer install
    • Generate key file by bash command 
      php artisan key:generate
    • Create symlink for /storage folder by bash command 
      php artisan storage:link
    • Run migrations and seeds by bash command 
      php artisan migrate --seed
    • Install node dependencies by bash command 
      npm install
    • Build frontend assets by bash command 
      npm run dev
    • Exit from app container by bash command: 
      exit
  • Check http endpoint by bash command 
    curl -I --insecure https://<APP_URI>
    • it should be:
    HTTP/1.1 200 OK ...
  • Administrator panel will be accessed by <APP_URI>/_admin, auth as <ADMIN_EMAIL> needed

AdminBar setup

  • Make sure that .env file on remote host contains following variables :

    • GIT_COMMIT=
    • GIT_BRANCH=
    • GIT_DATE=

  • Make sure that following commands were added to deploy CI/CD stage:

    • sed -i 's/GIT_COMMIT=.*/GIT_COMMIT=\""$CI_COMMIT_MESSAGE"\"/' .env &&
    • sed -i 's/GIT_BRANCH=.*/GIT_BRANCH=\""$CI_COMMIT_BRANCH"\"/' .env &&
    • sed -i 's/GIT_DATE=.*/GIT_DATE=\""$CI_COMMIT_TIMESTAMP"\"/' .env

PreCommit hooks

  • If pre-commit hook returns an error message code style errors, fix it by bash command and add changes to your commit: 
    docker-compose exec --user=flag app vendor/bin/composer csfix
  • For the run only code style validation use this bash command, Its will returns problem files list: 
    docker-compose exec --user=flag app vendor/bin/composer csfix-validate
  • If pre_commit hook contains test errors, check that you have local version of phpunit.xml, if not then run a bash command: 
    cp phpunit.xml.dist phpunit.xml
  • If pre_commit hook contains test errors, fix the tests and run the test again.

Graylog logging

  • Fill in variable GRAYLOG_HOST_IP in the .env.* file with the server address

Tests

  • Run test by bash command 
    docker-compose exec --user=flag app composer autotests

Database backups by app itself

  • Ссылка на документацию Laravel Backup
  • Use for start from the CLI: 
    php artisan backup:run --only-db
  • By default, the backpack will be uploaded by the zip archive in the path storage/app/{APP_NAME}, you can configure any other drives, including S3
  • The configuration file is located at config/backup.php

For advanced developers only!

Build and push base image

  • Check the .env file for filled by necessary variables
  • Run a bash command:
docker-compose -f docker-compose.build-base.yml build
  • Look at build result message, it should be like this:
Successfully built 47d8a9e3771b
Successfully tagged registry.gitlab.com/flagstudio/compose_project_name:base
  • At first, we need login to GitLab registry with deploy token
    • Settings for deploy token placed on Settings / Repository of yor GitLab repository:
      • https://gitlab.com/flagstudio/<PROJECT_NAME>/-/settings/repository
    • Run a bash command:
    docker login -u <CI_DEPLOY_USER> -p <CI_DEPLOY_PASSWORD> registry.gitlab.com
  • Now we can push this image to the GitLab registry of your project by bash command:
docker push registry.gitlab.com/flagstudio/<COMPOSE_PROJECT_NAME>:base

Build and push app image

If you need to build app image without CI builder & push it to the project registry follow this steps:

  • Checkout to the branch by bash command:
git checkout <BRANCH_NAME>;
git fetch && git rebase;
  • At first, we need login to GitLab registry with deploy token
    • Settings for deploy token placed on Settings / Repository of yor GitLab repository:
      • https://gitlab.com/flagstudio/<PROJECT_NAME>/-/settings/repository
    • Alternatively you can use your GitLab user_name & password
    • Run a bash command:
    docker login -u <CI_DEPLOY_USER> -p <CI_DEPLOY_PASSWORD> registry.gitlab.com
  • You need to provide special environment file for image building. In this example, we are provided .env.test
docker-compose --env-file .env.test -f docker-compose.build-app.yml build
  • Look at build result message, it should be like this:
Successfully built 4373b31e6b14
Successfully tagged registry.gitlab.com/flagstudio/compose_project_name:test
  • Now we can push this image to the GitLab registry of your project by bash command:
docker push registry.gitlab.com/flagstudio/<COMPOSE_PROJECT_NAME>:test

Deploy to server

  • Update or create necessary .env.* file, e.g.: .env.test for testing server
  • Fill required variables
  • Make database backup if needed, do not archive it
  • Make storage directory archive if needed;
  • For automated deploy use Ansible Deployer for deploy to external server
  • For manual deploy
    • ssh to the remote host
    • create www dir by the command mkdir -p /root/www
    • go to the www dir and clone traefik repo by command git clone [email protected]:flagstudio/traefik-staging.git
    • follow to the instructions from traefik readme.md
    • create project dir on remote host, e.g.: mkdir -P /root/www/project
    • copy docker-compose.*.yml file to the remote host as docker-compose.yml
    • copy .env.* to the remote host as .env
    • copy storage dir if needed
    • run on the traefik container
    • run on the project by command docker-compose up -d