Troubleshooting

“permission denied” talking to Docker

The SSH user is not in the docker group. Add it (usermod -aG docker <user>), or set docker_cmd: "sudo -n docker" for the server, which needs passwordless sudo for docker.

“host key mismatch”

The server’s key differs from the one in ~/.ssh/known_hosts. If you know the server was reinstalled, remove the old key with ssh-keygen -R <host> (or ssh-keygen -R '[host]:port' for a non-standard port) and connect again. Otherwise, treat it as a possible attack.

The Laravel tab is missing

laraport looks for artisan in the container’s root_path, /var/www/html and /app. If your app lives elsewhere, set root_path with e on the container list.

No database on the Data tab

The (app) entries need the database client (psql, mysql, redis-cli) in the app container or in the database’s own container on the same server, and a network host in the app’s config (not localhost or a socket).

The .env I edited has no effect

Values set in the container environment win over .env, and many platforms set them there. Check where a variable comes from on the Environment screen. If the app caches its config, run artisan config:cache.

Image updates say “can’t check”

The column says why:

• rate limited: Docker Hub answers 100 anonymous requests an hour per IP address. Try again later, or run docker login on the server, which raises the limit.
• no access: a private image. Run docker login for its registry on the server.
• docker buildx is not installed: the check reads registries with docker buildx imagetools. Install the buildx plugin on the server.

“… is read-only”

The server is marked read-only, and the action would change it. To change the server, press e on it in the home screen and switch off Read-only, or remove read_only: true from the config.

Restoring dumps is off

Restoring changes a database for good, so it is off by default. Switch on Allow restoring dumps in Settings (s on the home screen), or set allow_restore: true. See Restoring a dump.

A Compose action says a file “is not on this server”

Compose actions run in the directory the project was started from, with its compose and env files, as the container’s labels record them. If the project was started on another machine, or its files moved, the command stops and names the missing file. Run docker compose yourself in the project’s new place, or start the project again from there so the labels are updated.

When the container has no such labels at all, it was not started by Docker Compose, and the actions cannot run.

“Run now” refuses a scheduled task

t on the Schedule runs schedule:test --name=…, which finds tasks by name:

• no name it can find it by: a closure or job without a description. Give it a ->description('…').
• two tasks are called …: schedule:test cannot tell them apart. Give one a ->description().
• artisan refuses --name: the app runs Laravel 8 or older, where schedule:test has no --name.

Routes shows an error instead of the table

The app could not boot, so route:list failed, and the screen shows the app’s error. Warnings printed before the routes do not cause this: they are skipped. Fix the error and press r.

Redis keys says to narrow the pattern

The scan stops after 500 keys, or after 100 SCAN steps, so it never blocks a busy server. Use a narrower pattern, such as laravel_cache:user:* instead of *.

Events says older ones are gone

Docker keeps only its last 256 events. On a busy server they may cover less than the time you chose. The restart count on the container card and the container’s logs still tell you about earlier trouble.

No tunnel on the Data tab

The Tunnel to … entries need:

• a Laravel container with PHP, which relays the connections;
• a database or Redis on a network host in the app’s config, not localhost or a socket.

Copying does nothing

The tunnel’s u and p and the table view’s y copy through the terminal, with the OSC 52 escape sequence. Some terminals do not support it or have it turned off. In tmux, turn it on with set -g set-clipboard on.

A server’s check says ✗

c on the home screen connects to every server on a connection of its own. The line under a server that fails says why, for example a timeout, a refused key or an unknown host key.

An imported host is missing

Import from ~/.ssh/config leaves out hosts that are already configured (by name, or by user, host and port), aliases of the same machine, git hosts such as github.com, and patterns (Host *.example.com). A host that does not pass the server form’s checks is reported and skipped.

The errors summary covers only part of the log

For large logs the summary reads the last 64 MB. Press a to read the whole file. Only the summary travels to your computer, but reading several gigabytes still takes the server a while.

Composer cannot be installed in the container

When the container has no composer and the app ships no composer.phar, laraport downloads the installer into /tmp/laraport in the container. If that fails, the error says which step failed: no network access, a TLS problem, or allow_url_fopen turned off in PHP. Installing Composer in the image avoids the download.

No notice about a new version

The check runs once a day, and its answer is kept for a day in ~/.config/laraport/update.json. Development builds never check, prereleases are not offered, and a failed check stays silent. The check is off when Check for new versions is off in Settings or LARAPORT_NO_UPDATE_CHECK is set.

Something else

Open an issue on GitHub with what you did and what you saw.