servd

Documentation

Documentation > Common Tasks >

Start a Shell Session (SSH)

You can start a shell session within one or more of your project's application instances and connect to it via SSH in order to explore your project's filesystem in real time.

Any changes made to the filesystem will not persist indefinitely! See the Limitations section below for more information.

Starting a Shell Session #

  1. Navigate to your project's Production, Staging or Development Commands page in the Servd dashboard.

  2. Click the "Start A New Session" button.

  3. Once the shell is ready, a connection string will appear which you can copy and paste into a local terminal window.

Stopping a Shell Session #

It is best practice to stop a shell session whenever you have finished using it. You can do this in three ways:

  • Logging into the shell session and running exit
  • Clicking the 'End Active Sessions' button in the Servd dashboard for the environment you'd like to clean up
  • Deploying a new bundle

When you end a shell session using any of these methods all connected users will be disconnected immediately.

'An SSH session is already running' Error #

This error is displayed whenever the project instance selected for the shell already has an active session running. You can either connect to the existing shell session or, if you no longer have the old connection string, click the 'End Active Sessions' button in the Servd dashboard and then retry creating a new session.

Limitations #

  • Any changes made to the filesystem will not persist indefinitely! Servd uses ephemeral filesystems to keep your project secure and allow features like full-filesystem rollbacks, but this also means any changes you make will be lost whenever you deploy a new bundle.
  • Changes you make will only be present on one of potentially several load balanced instances.
  • If you are attempting to find logs on a specific host, you might need to create multiple sessions until the host you are interested in is selected as the target for the shell.
  • You will be connected as the www-data user. This user will be able to perform all of the operations normally executed by PHP and can run ./craft CLI commands, but will not be able to install additional software or make changes to system files.
  • It is strongly recommended that you do not run any composer commands which might modify the filesystem. These changes will not persist across bundle deployments, but any database data changes which occur as a result (such as with a Craft update) will persist, potentially resulting in a broken project state.