Knowledgebase / Website & Applications / How to set up Laravel on your onion service

How to set up Laravel on your onion service

A PHP onion service is a plain Apache + PHP container, so Laravel runs on it as soon as the framework is in place and Apache is pointed at its public directory. This guide does it from the command line over SSH: create the project with Composer, generate the application key, wire the database, and check that the welcome page loads over Tor.

If you only need the standard skeleton, the portal can also install Laravel for you when the service is created (choose PHP Website Hosting and the Laravel framework on the create page). The steps below are for an existing service, or when you want to control the version and the structure yourself.

Step 1 — Check the PHP version

Laravel 11 needs PHP 8.2 or newer. The container for this guide reports PHP 8.2.35. If your service is on an older version, switch it in the portal first (Version tab), then connect over SSH and confirm:

php -v
composer -V

Both are already installed — you do not have to install PHP or Composer yourself.

Step 2 — Allow outbound traffic (or bring vendor with you)

Outbound traffic is blocked by default on a new service, and Composer has to reach packagist.org to download the framework. Enable it in the portal (Outbound tab) for the duration of the install, or skip Composer on the server entirely by running composer install on your own machine and uploading the project including vendor/ — see How to upload a large application to your onion service.

Step 3 — Connect over SSH and create the project

Connect as described in How to connect to your onion service with SSH (port 2222, user www-user, your key). You land in /var/www/html, which is the web root. The shell is restricted: cd and > are refused, so pass the target directory to Composer instead of changing into it:

pwd                                    # /var/www/html
composer create-project laravel/laravel /var/www/html/app

Measured on a Starter service: the whole install took about three minutes, and Composer already ran the skeleton's post-install steps (it creates .env from the example, generates the application key and runs the default migrations against the bundled SQLite file). git is not installed in the container; Composer downloads distribution archives, which is what you want, but a package that only exists as a repository will fail and has to be uploaded instead.

Step 4 — Configure the application

cp /var/www/html/app/.env.example /var/www/html/app/.env
php /var/www/html/app/artisan key:generate

key:generate writes the APP_KEY; without it every session and every encrypted value breaks. Composer normally runs this for you — run it again after you copy your own .env, because that copy overwrites the generated key. Then set the application URL in .env to your onion address:

APP_NAME=Laravel
APP_URL=http://your-address.onion
APP_ENV=production
APP_DEBUG=false

Use http:// unless you have enabled SSL/TLS — and if you did, keep https:// together with APP_URL, otherwise Laravel keeps generating links to the wrong scheme.

Step 5 — Serve Laravel from the web root

Apache serves /var/www/html, but a Laravel application must be entered through its public directory. Put a rewrite in the web root that forwards everything into it. The restricted shell cannot write a file (no >, no tee, no bash -c), so create .htaccess on your computer and upload it to www with the SFTP client:

<IfModule mod_rewrite.c>
    RewriteEngine On
    RewriteRule ^(.*)$ public/$1 [L]
</IfModule>

Keep the application itself one level up from the entry point like this: app/ holds the framework, and the only file Apache can reach directly is app/public/index.php. If /app/.env were reachable from the browser it would hand out your database password.

Step 6 — Permissions

You unpacked or created the files as www-user, while Apache runs as www-data. Laravel needs to write two directories at runtime:

chmod -R 777 /var/www/html/app/storage /var/www/html/app/bootstrap/cache

777 looks crude, and on a normal server you would use a shared group instead; in this container the two users do not share one and there is no sudo, so this is the setting that works. Everything else can stay read-only for Apache.

Step 7 — Connect the database

The service's database is a separate container; the hostname is db, not localhost. The name, user and password are on the portal's Database tab:

DB_CONNECTION=mysql
DB_HOST=db
DB_PORT=3306
DB_DATABASE=your_database_name
DB_USERNAME=root
DB_PASSWORD=the-root-password-from-the-database-tab

Then create the tables:

php /var/www/html/app/artisan migrate

If you already have a dump of the database, import it first — How to import a large MySQL dump into your onion service.

Step 8 — Check it over Tor

Open your onion address in the Tor Browser. You should get the Laravel welcome page; a 500 at this point is almost always storage/bootstrap/cache permissions or a missing APP_KEY, and the message is in app/storage/logs/laravel.log:

tail -n 40 /var/www/html/app/storage/logs/laravel.log
php /var/www/html/app/artisan about

Do not leave php artisan serve running as a "web server": it is the development server, single-threaded and not meant to face the network. The Apache container is already serving the site.

Step 9 — Updating the application later

composer install --no-dev --optimize-autoloader --working-dir=/var/www/html/app
php /var/www/html/app/artisan migrate --force
php /var/www/html/app/artisan config:cache
php /var/www/html/app/artisan route:cache
php /var/www/html/app/artisan view:cache

Run those after every upload, and clear the caches (php /var/www/html/app/artisan optimize:clear) if a change does not show up — cached config is the usual reason a new .env value is ignored.

Related articles

Tags:
  • Onion Service
  • Laravel
  • PHP Framework

24/7 Expert Support

Our experts are always on hand to help answer your questions, get you started, and grow your presence online. You can email us any time