umi-blueprint

1. install docker

   • on Windows turn on your installed WSL distribution in Docker: settings ~> resources
   • check that your BIOS settings has a Virtualization option and it's enabled

2. run command in terminal cp .env.local .env (in project root folder)

3. .env -- replace APP_NAME, COMPOSE_PROJECT_NAME to your app name; replace DB_HOST to mysql

   Example:

   APP_NAME=umi-blueprint
   DB_HOST=mysql
   COMPOSE_PROJECT_NAME=umi-blueprint.test

4. IF you need NODE / REDIS services for development, add this to docker-compose.yml >> services section

     redis:
       image: redis
       container_name: ${COMPOSE_PROJECT_NAME}-redis
       ports:
         - 6379
       <<: *networks
   
     node:
       build:
         context: ./docker/node/
         dockerfile: ./Dockerfile
       container_name: ${COMPOSE_PROJECT_NAME}-node
       volumes:
         - ./:/var/www/${COMPOSE_PROJECT_NAME}
       <<: *working_dir

   For REDIS your also need to add nginx dependency

     nginx:
       depends_on:
         ...
         - redis

   IF your containers already running (check statuses with docker-compose ps) and you are adding new services,
   rebuild them with docker-compose up -d --build
   IF you need a certain version of NODE, specify it in the config
   /docker/node/Dockerfile >> FROM node:specific_version_number (autocomplete will give you all options)

   Docker generates dynamic ports every time when you build containers. you can add (in project root folder) docker-compose.override.yml to make your project ports static. So after container's rebuild you will always see your project on the certain port:

   # Example of docker-compose.override.yml
   services:
     nginx:
       ports:
         - 7000:80
   
     mysql:
       ports:
         - 7706:3306
     # you may need it for laravel projects in case of user rights error
     php:
       user: "1000:1000"
   
   # `7000` is a desired port.

5. add COMPOSE_PROJECT_NAME value from .env to your hosts file as 127.0.0.1 project_name_you_choose

6. change the folder template name of you PROJECT inside templates folder

7. start docker in terminal -- docker-compose up -d (in project root folder)

8. type in terminal docker-compose ps and get port from nginx service (or use docker-compose.override values).

9. project will be available by the address http://project_name_you_choose:port

   in case of 403 error go to nginx cli in docker desktop and type chmod -R 775 [folder name]

10. Import DB (you have 2 options) After installing UMI / pulling core files from digital

    containers need to be running. check statuses with docker-compose ps

    First option - command line

    • place your DB dump (rename it as backup) into folder /docker/mysql/dump/
      Support all default extensions *.sql/*.sql.gz/*.tgz

    if you have problems with import archived mysql files then use gunzip on file to unzip it first

    • use command terminal with bash (PowerShell / GitBash on Windows) support and run commands:

     > . /docker/mysql/backup.sh (`.` is a command)
     > restore_database

    • wait until progress bar finish at 100%

    OR

    Second option - manual import

    You can add your database dump manually.

    • set database connection via any database gui (Workbench, MyAdmin, Navicat, etc.):
      get credentials from .env + docker-compose ps and get port from mysql
    • import your DB dump to database

11. install UMI in trial mode, without template

    • during the installation fill DB host field as mysql and set DB credentials from your .env file

After UMI installed

• config.ini inside PROJECT folder -- replace PROJECT with the name of you project

• root config.ini in [connections] section -- change mysql host to core.host = "mysql"

• templates/PROJECT/classes/sitePhpExtension.php -- replace PROJECT inside with correct settings "container_id"

• add all dependencies to composer.json and run docker-compose exec php composer install (in project root folder)

• all resources (js/css/fonts/images etc.) are placed in templates/PROJECT/public/. Run commands to build frontend (if exist).

Prepare CI/CD environment

• .gitignore -- replace PROJECT with the name of you project folder
• .git-ftp-ignore -- replace PROJECT with the name of you project folder

frontend can skip this step >>

GitHub.com

• add DEPLOY_USER / DEPLOY_KEY (private) and SLACK_BOT_TOKEN to secrets section
• .github/workflows/deploy-pipelines.yml -- replace PROJECT with the name of you project folder / domain name of you dev env
• fill all necessary variables in env section

inetstudio.gitlab.yandexcloud.net

• add DEPLOY_USER / STAGING_PRIVATE_KEY to CI/CD variables section
• .gitlab-ci.yml -- replace PROJECT with the name of you project folder / domain name of you dev env
• fill all necessary variables in variables section

<< frontend can skip this step

Prepare Sentry.io monitoring integration

• create 2 separate projects for frontend and backend teams with the PROJECT-frontend/backend names
• add VERSION_POSTFIX environment variable inside VCS system which will represent your PROJECT name

Troubleshooting

• In case of 403 error (UMI IS installed) go to nginx cli in DockerDesktop OR in linux / WSL terminal and type chmod -R 775 [folder name]
• In case of 504 error during UMI installation go to docker/nginx/templates folder and add new line fastcgi_read_timeout 240 inside location ~ \.php$ { ... } section of template file.

ARM processors (MacBooks, BitBlaze etc.) issues

• In case of MySQL errors when building containers (using docker compose up -d command),
  try to change image in /docker/mysql/Dockerfile to FROM mariadb:10.8 also check that COMPOSE_PROJECT_NAME don't contain “.” else replace it with “-”