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
vagrantalso 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),
sudowithout a password
- Just prefix
some commandthat runs into permission issues like
sudo some commandand 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.
All logs are stored in
/var/log including all system environment logs. The most important ones are:
/var/log/nginx/error.logfor Webserver errors
/var/log/php.logfor 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.logeverything about SSR
dev/frontend.loglogs from the Backend-for-Frontend (Symfony logs)
<customer>-<project>-yarn.logcontains the webpack logs for browser compilations on the specific Project
replicator.logthe logs of the Replicator
supervisord.logthe supervisor logs (see below)
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 prepareensures that all dependencies are in place, database is updated, etc.
ant testexecutes all available automated tests
You can find more info in this article (link to come).
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:clearclears all data from your Project so that it will be re-applied from Backstage using the Replicator
bin/console frontastic:routes:rebuildrebuilds the routing based on the Nodes in Frontastic
bin/console cache:clearwill 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
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
The most useful available sub-commands are:
sudo supervisorctl statusto 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
The most important tasks running in Supervisor are:
replicatorthe 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.
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
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