Debugging Your Bench with SSH

SSH access gives you the ability to inspect your bench, analyze logs, run diagnostic commands, and troubleshoot issues with custom apps. It is intended for debugging and maintenance—not for modifying your production environment.

Warning

Use SSH only for debugging purposes. Running configuration-changing Bench commands can break your Frappe Cloud environment. Avoid commands such as bench setup supervisor or other production setup commands.

Things to Avoid

To prevent issues with future deployments and updates, avoid the following actions after connecting through SSH:

Creating or downloading apps directly on the bench
Commands like:
```
bench new-app my_app
bench get-app my_app
```
only affect the current bench version and will be lost after the next bench deployment.
Installing manually added apps on a site
Installing an app that was added directly through SSH can prevent future site updates. If this happens, uninstall the app before updating the site.
Editing frontend assets
Avoid modifying CSS or JavaScript files and running:
```
bench build
```
This can break frontend assets on the bench. If it happens, redeploy the bench and update your site from the dashboard.

Reading Bench Logs

After connecting through SSH, navigate to the logs directory. The most commonly used log files include:

web.log – Standard output for web requests.
web.err.log – Errors generated by web requests.
worker.log – Standard output for background workers.
worker.err.log – Errors generated by background jobs.

Useful commands for viewing logs:

less +G logs/web.err.log
tail -f logs/web.log

Tip

Use less +G to open a log from the bottom of the file, or tail -f to watch new log entries in real time while reproducing an issue.

Useful Bench Commands

Several Bench commands can help diagnose problems without changing your environment.

bench doctor – Check the health of workers and scheduled jobs.
bench restart – Restart Bench processes after making temporary code changes during debugging.

Inspecting the Database

You can open the MariaDB console directly from your bench:

bench mariadb

For example, view currently running database queries with:

SHOW PROCESSLIST;

Checking Supervisor Processes

Supervisor manages all processes running on your bench.

To view their current status, run:

supervisorctl status

In a healthy bench, every process should display the RUNNING state.

Best Practice

If one or more processes are not running, review the corresponding log files before attempting a restart. The logs usually identify the root cause of the failure.

Connecting to Redis

Once connected through SSH, you can inspect the Redis services used by your bench with the following commands:

redis-cli -p 13000   # Cache
redis-cli -p 12000   # Socket.IO
redis-cli -p 11000   # Queue

These Redis instances can help you troubleshoot caching, queues, and realtime events when debugging application behavior.

Rating: 0 / 5 (0 votes)