Can't figure out how to get debugging working on remote server

The Basics

  • Nextcloud Server version (e.g., 29.x.x):
    • Nextcloud Hub 10 (31.0.6)
  • Operating system and version (e.g., Ubuntu 24.04):
    • Ubuntu 24.04.2 LTS
  • Web server and version (e.g, Apache 2.4.25):
    • Apache/2.4.58 (Ubuntu)
  • PHP version (e.g, 8.3):
    • PHP 8.3.6
  • Installation method (e.g. AlO, NCP, Bare Metal/Archive, etc.)
    • VM running in XCP
  • Are you using CloudfIare, mod_security, or similar? (Yes / No)
    • No

Summary of the issue you are facing:

I have successfully installed Nextcloud on my remote server and can access it from the browser. This remote server is in the same network as my workstation. I have a DNS server setup so that I can access the Nextcloud web console using a FQDN. I installed Nextcloud following the Ubuntu installation guide in the docs.

Now I am wanting to do remote debugging from my workstation via VSCode. This is where I am having some trouble. I have looked at the docs and tried watching some YouTube videos, but none of it really makes sense to me as this is my first time trying to do something like this.

I have xdebug installed on my remote server and can see it is enabled when running phpinfo();.

After this I am not sure what else to do. If anyone could give some guidance I would be very grateful. If I have missed any useful info, please ask and I will answer to the best of my ability.

Thank you.

Configuration

Nextcloud

{
    "system": {
        "debug": true,
        "passwordsalt": "***REMOVED SENSITIVE VALUE***",
        "secret": "***REMOVED SENSITIVE VALUE***",
        "trusted_domains": [
            "localhost",
            "<FQDN Here>",
            "<Server IP Here>"
        ],
        "datadirectory": "***REMOVED SENSITIVE VALUE***",
        "dbtype": "mysql",
        "version": "31.0.6.2",
        "overwrite.cli.url": "http:\/\/localhost",
        "dbname": "***REMOVED SENSITIVE VALUE***",
        "dbhost": "***REMOVED SENSITIVE VALUE***",
        "dbport": "",
        "dbtableprefix": "oc_",
        "mysql.utf8mb4": true,
        "dbuser": "***REMOVED SENSITIVE VALUE***",
        "dbpassword": "***REMOVED SENSITIVE VALUE***",
        "installed": true,
        "instanceid": "***REMOVED SENSITIVE VALUE***",
        "maintenance": false,
        "maintenance_window_start": 1,
        "memcache.local": "\\OC\\Memcache\\APCu",
        "memcache.locking": "\\OC\\Memcache\\Redis",
        "redis": {
            "host": "***REMOVED SENSITIVE VALUE***",
            "port": 6379,
            "timeout": 0,
            "password": "***REMOVED SENSITIVE VALUE***"
        },
        "default_phone_region": "US"
    }
}

Apps

Enabled:

  • activity: 4.0.0
  • app_api: 5.0.2
  • bruteforcesettings: 4.0.0
  • circles: 31.0.0
  • cloud_federation_api: 1.14.0
  • comments: 1.21.0
  • contactsinteraction: 1.12.0
  • dashboard: 7.11.0
  • dav: 1.33.0
  • federatedfilesharing: 1.21.0
  • federation: 1.21.0
  • files: 2.3.1
  • files_downloadlimit: 4.0.0
  • files_pdfviewer: 4.0.0
  • files_reminders: 1.4.0
  • files_sharing: 1.23.1
  • files_trashbin: 1.21.0
  • files_versions: 1.24.0
  • firstrunwizard: 4.0.0
  • logreader: 4.0.0
  • lookup_server_connector: 1.19.0
  • nextcloud_announcements: 3.0.0
  • notifications: 4.0.0
  • oauth2: 1.19.1
  • password_policy: 3.0.0
  • photos: 4.0.0-dev.1
  • privacy: 3.0.0
  • profile: 1.0.0
  • provisioning_api: 1.21.0
  • recommendations: 4.0.0
  • related_resources: 2.0.0
  • serverinfo: 3.0.0
  • settings: 1.14.0
  • sharebymail: 1.21.0
  • support: 3.0.0
  • survey_client: 3.0.0
  • systemtags: 1.21.1
  • text: 5.0.0
  • theming: 2.6.1
  • twofactor_backupcodes: 1.20.0
  • updatenotification: 1.21.0
  • user_status: 1.11.0
  • viewer: 4.0.0
  • weather_status: 1.11.0
  • webhook_listeners: 1.2.0
  • workflowengine: 2.13.0
    Disabled:
  • admin_audit: 1.21.0
  • encryption: 2.19.0
  • files_external: 1.23.0
  • suspicious_login: 9.0.1
  • twofactor_nextcloud_notification: 5.0.0
  • twofactor_totp: 13.0.0-dev.0
  • user_ldap: 1.22.0

I think I have everything working so I will post my steps here for anyone else that may be struggling.

Basic Info


Nextcloud is running in a VM on a XCP host. Keep this in mind when you read this since your installation might be different.

Install xdebug on your


The VM OS is Ubuntu 24.04 LTS so I did this to install xdebug:
sudo apt install php-xdebug

Ensure that xdebug is installed properly


To do this I created a new php, named xdebuginfo.php file that could output the xdebug info. The file contained the following:

<?php
xdebug_info();
?>

Now you can go to your Nextcloud in the browser and access that file, like so:
`/xdebuginfo.php

You should see something like this if xdebug is installed properly:

Note: This screenshot is from AFTER xdebug is installed and working properly, so your values will look different. The main thing here is that this page shows up so you know that xdebug is installed properly.

Edit xdebug ini on the server


On the xdebug page from the previous step you can find the proper ini file that should be edited. I just did a search on the page for xdebug.ini to find it. For me it was the following path:
/etc/php/8.3/apache2/conf.d/20-xdebug.ini

Your file will likely only contain the line zend_extension=xdebug.so or something similar. Here are the changes I made:

zend_extension=/usr/lib/php/20230831/xdebug.so
xdebug.mode=debug,develop
xdebug.start_with_request=yes

Note: The numbered directory will be different for you. Just cd to /user/lib/php/ and look for your numbered directory.

Restart apache2 and check the xdebug page again


Pretty straight forward, just do sudo systemctl restart apache2 and go back to the xdebuginfo.php page. You should see that the Deployment Helpers and Step Debugger are now enabled.

Connect with your preferred IDE
For this section, I am personally using PhpStorm. I am unsure of how VSCode would work with this but I will update this reply if I look into it.

For PhpStorm I started by creating a new SSH connection to the server. Simply open PhpStorm, click SSH on the left under Remote Development, then click New Project.

Input all the info required to create the SSH connection and click ‘Check Connection and Continue’.

Now you should have project that SSHs to your remote server. From here you can click on Run → Start Listening for PHP Debug Connections. This will tell PhpStorm to listen for incoming xdebug connections. Xdebug may not be installed in your PhpStorm so it may ask you to install it.

Enable debugging im the browser
I am using Firefox at the moment. There is a plugin called xdebug helper that will set the proper cookies for xdebug. With this plugin installed you can look at the address bar and there will be a little debug icon at the end. Click this, then click debug to start the debugging.

Test Connection


Xdebug should be working now so you can put a breakpoint somewhere in the code where you know will be hit when you load a page. For me I put a breakpoint in the security middleware since this is a common controller that is hit when accessing basically anything in Nextcloud. It is located under lib/private/AppFramework/Middleware/Security/SecurityMiddleware.php. I put a breakpoint on isAdminUser().

Conclusion


This should be everything you need to get it working. Remember that your installation will likely be different than mine so some of the steps will be different. This is just a quick guide on how I got it working in my particular case.

Feel free to ask any question and I will be my best to help where I can. This was a very confusing process for me since I have never had to do remote debugging before, so I completely understand if there is any frustration.

Good luck everyone with your projects! :grinning_face_with_smiling_eyes:

1 Like

Glad to hear you got it working!

If you feel so inclined, consider proposing some changes to the NC dev xdebug docs: