Skip to content
GRIMOIRY

Step into a server container

$ grim remote:shell

One command at a time is not enough. You want to look at the files the image really contains, check what the process sees in its environment, run a few artisan commands in a row and read the output of each before deciding the next. grim remote:shell puts you inside the running container on the server, the same way grim shell does on your machine.

For a single command, grim remote:artisan and grim remote:exec are quicker.

Usage

$ grim remote:shell               # bash in the app container
$ grim remote:shell horizon       # the queue workers' container
$ grim remote:shell scheduler     # the container that runs the schedule

Run it from the project directory, in a real terminal, on a machine where the project's server is registered in ~/.grim/servers.json.

Arguments and options

Open an interactive bash shell inside the remote production app container

Usage

grim remote:shell [<service>]

Arguments

Argument Description
service Docker compose service (default: app) (optional, default: app)

What it actually does

  1. Finds the server in ~/.grim/servers.json, using the project's default environment there. There is no environment argument; grim remote:artisan explains what that means for staging.
  2. Prints where it is going. Opening shell on shop (203.0.113.10) in container app... and a reminder that exit brings you back.
  3. Opens the session. SSH as the deploy user with a terminal, a cd into the project's directory, then docker compose exec <service> bash.
  4. Hands you back when you type exit or press Ctrl+D, with the exit code of the session.

Pitfalls

Only the PHP containers have bash

app, horizon, scheduler and reverb run the project's image and have bash. nginx and redis are Alpine images without it, and the attempt ends with exec: "bash": executable file not found in $PATH. Ask for sh through the other command: grim remote:exec docker compose exec redis sh.

There is no database container to enter

On a server raised by grim, MySQL runs on the host and not in the project's stack, so grim remote:shell mysql fails: the stack has no such service. Reach the database from the app container, with php artisan tinker.

What you change does not last

The container's filesystem is replaced at the next release, and at every restart that recreates it, grim env:set included. A file edited in place to test a fix is gone then. What survives is the database, the storage volume and the .env.

You are inside production with the app's own database credentials loaded. Nothing asks twice. Prefer reading to writing, and make a change the normal way, through a release, once you know what it should be.

After it finishes

Nothing stays running on the server; the session ends with the shell. The investigation this command is usually part of is written up as the recipe Debug production.

grim remote:artisan

Run artisan on the server

Run one artisan command inside the app container of the deployed project, from your own terminal.

grim remote:exec

Run a command on the server

Run one shell command on the server, in the deployed project's directory, without opening an SSH session yourself.

grim shell

Step inside a container

Open an interactive bash session in the app container, or in another service of the local stack.

grim server:add-project

Give a project a home

Prepare one environment of a project on a production server, with its database, nginx vhost, certificate, compose stack and .env.

Recipes that use it

Debug production

Look at the server, read what the app logged, search the log on the server, question the app through artisan, turn the log level up for a while, and go inside the container when nothing else answers.