System Structure (VM/Container)

If you're into heavy debugging or are just curious how things work, looking into how the VM/Container (VM) is structured could help so we wanted to share that with you.

Within the VM, you can see server logs (including Server Side Rendering (SSR) logs), look into the database, clear caches, and more!

To boot/restart the VM using Vagrant, follow the steps in this article. Then, you can reach into the VM using vagrant ssh. This brings you to a Linux shell inside the VM and in the directory where your source code is mirrored to and from where it's run (/var/www/frontastic), so you can, for example, cd into your project folder. You should know the basics of Linux shell to work in here, a good overview can be found here: Basics of BASH for Beginners.

User / Permissions
  • You're the user vagrant
  • vagrant also runs the Webserver so you shouldn't run into permission issues when editing files
  • If you still need to do something as root (for example, restart supervisor or read system logs), vagrant can sudo without a password
  • Just prefix some command that runs into permission issues like sudo some command and it will run

Please don't edit any system configuration files! Everything is automatically set up to mimic your Production system as much as possible. Changing configuration manually voids support in case of an error!

That said, you can change anything for debugging or for learning purposes but be sure to destroy and re-create the VM afterward to come back to a sane state.

Logs

All logs are stored in /var/log including all system environment logs. The most important ones are:

  • /var/log/nginx/error.log for Webserver errors
  • /var/log/php.log for PHP problems

All Frontastic application logs reside in /var/log/frontastic, the structure is:

  • <customer>_<project> contains all logs for a specific Project, for example:
    • ssr.log everything about SSR
    • dev/frontend.log logs from the Backend-for-Frontend (Symfony logs)
  • <customer>-<project>-yarn.log contains the webpack logs for browser compilations on the specific Project
  • replicator.log the logs of the Replicator
  • supervisord.log the supervisor logs (see below)
Build Stack

We use ant to encapsulate all parts of the Project build stack. You should use ant to run tasks in a standardized way.

The following commands work on the top-level (executing them for all Projects + the libraries) or inside a Project directory (only for this Project):

  • ant prepare ensures that all dependencies are in place, database is updated, etc.
  • ant test executes all available automated tests

You can find more info in this article (link to come).

Symfony Commands

Inside of every Project directory, you can run bin/console to access many Backend-for-Frontend-related commands (Symfony command line). If you execute it without parameters, you will be shown all the available commands (there are a lot!).

You won't need most of them, but sometimes there are edge-case where the below could come in handy:

  • bin/console frontastic:clear clears all data from your Project so that it will be re-applied from Backstage using the Replicator
  • bin/console frontastic:routes:rebuild rebuilds the routing based on the Nodes in Frontastic
  • bin/console cache:clear will clear the backend cache which might be needed after certain backend code changes (for example, Symfony dependencies)
  • If you're working on the Backend-for-Frontend code, you might find the Symfony debugging commands helpful, too, which are all prefixed by debug:
Supervisor

The Frontastic Catwalk doesn't only consist of the Webserver, PHP Backend-for-Frontend, and some code files, but also some long-running process that handles tasks in the background. To maintain these tasks properly, we use a tool called Supervisord.

The central entry point for seeing the status and managing these commands is the command sudo supervisorctl (which needs to be started with sudo). 

The most useful available sub-commands are:

  • sudo supervisorctl status to see all tasks maintained by Supervisor and if they're running, stopped, errored, etc.
  • sudo supervisorctl restart ['<task>'|all] to restart one or all tasks (advanced usage see the help of supervisorctl!)

The most important tasks running in Supervisor are:

  • replicator the Replicator that pulls changes from Backstage
  • ...server-run... the NodeJS running the compiled SSR build per Project
  • ...server-webpack... the webpack instance re-building the SSR build on change per Project
  • ...browser-webpack... the webpack instance for host-serving the browser assets (JS, CSS, …) per Project

If any of these for the Project you're working on is in a stopped or errored state, you should try to restart and look into the logs (see above) if this doesn't help.

MySQL

Frontastic uses MySQL to store the configuration (Nodes, Pages, etc.) for the Catwalk projects. It's very unlikely that you'll need to look into this directly, but if you're curious...

To access MySQL you can run mysql -uroot -p on the shell and use the password root to gain access. This will open the MySQL interactive shell where you can run MySQL commands (close using <Ctrl>+<d>).

There's a database for each Project and you can inspect those using:

  • show databases; to see all databases
  • use <database>; to switch to a certain database
  • show tables; to see all tables in that database
  • describe <table>; to see the Schema of a certain table

Of course, you can use the regular SQL commands to look into tables and even change data.

Please don't change any database content! This voids support in case of an error!

If you've changed the database content, you can get back to a clean state using the bin/console frontastic:clear (command) or even better by re-creating your VM using vagrant destroy and vagrant up again


‹ Back to Article List


Still need help? Contact Us Contact Us