System structure (Frontastic sandbox)
If you're into heavy debugging or are just curious how things work, looking into how the Frontastic sandbox is structured could help so we wanted to share that with you.
Within the Frontastic sandbox, you can see server logs (including Server Side Rendering (SSR) logs), look into the database, clear caches, and more.
To bring up the Frontastic sandbox, follow the steps in the Bringing up a Frontastic sandbox article. Then, you can reach into the Frontastic sandbox using
ssh [email protected]<your-machine-host> (see the Frontastic studio for the password).
This brings you to a Linux shell inside the Frontastic sandbox 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.
- 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 Frontastic sandbox afterward to come back to a normal 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 plus the libraries) or inside a project directory (only for this project):
ant prepareensures that all dependencies are in place, the database is updated, and so on
ant testexecutes all available automated tests
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'll be shown all the available commands (there are a lot!).
You won't need most of them, but sometimes there are edge-cases where the below could come in handy:
bin/console frontastic:clearclears all data from your project so that it will be re-applied from the Frontastic studio using the Replicator
bin/console frontastic:routes:rebuildrebuilds the routing based on the page folders 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 API hub 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, and so on
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 the Frontastic studio
...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 (page folders, page versions, and so on) for 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.
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 destroying your Frontastic sanbox and bringing up a new one.
Updated about 1 year ago