RackHelm
Get a demo key
View Categories

Automated Installation with install.sh

7 min read

0:00 7:21
Table of Contents

install.sh ships inside the RackHelm release archive and deploys the files that sit alongside it. It asks eight or so questions, then installs PHP, nginx, Redis, MySQL, Supervisor and the ionCube Loader, builds the front end, runs the database migrations and prints your admin credentials. Budget ten to twenty minutes on a clean server.

Before you start #

  • A freshly provisioned Debian, Ubuntu or RHEL-family server. See System requirements.
  • Root access.
  • A DNS A record for your portal hostname already pointing at the server, and port 80 reachable from the internet — Let’s Encrypt validates over HTTP.
  • Your RackHelm licence key.
  • If you are using a remote database: its host, port, name, username and password.

Warning: Run the installer on a server that has nothing else on it. It rewrites the nginx site configuration, removes nginx’s stock default site, sets a MySQL root password, and applies ownership across /var/www/rackhelm.

Running it #

  1. Upload the release archive to the server and extract it.
  2. Change into the extracted directory. The installer deploys the files that sit beside it, and refuses to start unless artisan and .env.example are in the same directory as install.sh — so do not copy the script out of the archive.
  3. Run it as root: 
    sudo bash install.sh
Terminal showing the RackHelm Installer banner and the first configuration prompt
The installer opens with a banner, then the Configuration section where every question is asked up front.

The questions, in order #

All prompts are asked before anything is installed, so you can walk away once you have answered them.

Prompt What to enter
Do you want to continue anyway? (y/n) Only appears on an unrecognised distribution. Answering y proceeds using Debian conventions.
App URL (e.g., portal.example.com) The hostname only — no https://, no trailing slash. This becomes the nginx server_name, the certbot domain, and the host part of APP_URL. RackHelm only trusts requests whose Host header matches it, so get it right first time.
License Key Your RackHelm licence key. It is written to .env as RACKHELM_LICENSE_KEY and used for the runtime check. Nothing else in the installer needs it.
Do you want to automatically install a Let’s Encrypt SSL certificate? (Y/n) Defaults to yes — pressing Enter installs a certificate. Answer n only if TLS is terminated somewhere else.
Are you running behind a reverse proxy or Cloudflare using HTTPS? (y/N) Only asked when you declined the certificate. Answer y when something in front of the server already serves HTTPS, so that APP_URL is still written with an https:// scheme.
Select option (1 or 2) 1 installs a local MySQL/MariaDB server and generates credentials. 2 uses an existing database you provide.
Database Host / Port [3306] / Name / Username / Password Only asked for option 2. The port defaults to 3306 if you press Enter.

Choosing option 1 gives you a database called rackhelm, a user called rackhelm_user on 127.0.0.1, and 32-character random passwords for both that user and the MySQL root account.

Tip: If you answer n to the certificate question and N to the reverse-proxy question, the portal will be served over plain HTTP — and logins will fail with a 419 error, because the session cookie is HTTPS-only. See Web server, SSL and HTTPS.

What each stage does #

After the questions the installer prints six stages, each with a spinner and either Done or Failed. Every stage writes to its own log under /var/log/.

Stage What happens Log file
Updating system packages and prerequisites Adds the NodeSource and PHP repositories, installs every OS package, verifies Composer’s installer signature before running it, then downloads and enables the ionCube Loader for FPM and CLI — aborting immediately if the Loader is not active for CLI. /var/log/rackhelm_install_sys.log
Deploying application files Copies the extracted tree into /var/www/rackhelm, creates storage and bootstrap/cache, deletes any stale compiled caches that rode along in the archive, and applies SELinux contexts on RHEL. /var/log/rackhelm_install_deploy.log
Configuring environment Copies .env.example to .env, then writes APP_URL, APP_ENV=production, APP_DEBUG=false, the DB_* block, the Redis driver settings, the pinned Redis prefixes, your licence key and a freshly generated APP_KEY. Finishes by locking .env to root:<web user> mode 640. /var/log/rackhelm_install_env.log
Installing dependencies, building application, and configuring servers in parallel Four concurrent threads: composer install --no-dev --optimize-autoloader; npm install then npm run build; the MySQL database, user and root password (option 1 only); and the nginx site, Supervisor program for Horizon, firewall rules and certbot. rackhelm_install_composer.log, rackhelm_install_npm.log, rackhelm_install_mysql_config.log, rackhelm_install_servers.log
Running Laravel migrations and setup Runs php artisan migrate --seed --force as the web user, then view:cache and storage:link, and tightens permissions on storage and bootstrap/cache. /var/log/rackhelm_install_artisan.log
Securing file permissions Sets the whole tree to root:<web user> read-only, gives the web user ownership of storage and bootstrap/cache only, and re-applies 640 to .env. /var/log/rackhelm_install_perms.log

Because the fourth stage runs four things at once, a failure there names the threads that broke — for example Failed stage(s): npm servers — and prints the matching log paths, so you do not have to diff four logs by timestamp.

Note: All /var/log/rackhelm_install_*.log files are set to mode 600, because they contain database passwords and other configuration secrets. The Artisan log is additionally rewritten so the seeded admin password reads [redacted].

Reading the final output #

On success the installer prints a completion banner and then, in order:

  1. The live URL — https:// when a certificate was installed, otherwise http://.
  2. Database Details — database name, username, generated password and MySQL root password. These are shown only when you chose the local-database option, and they are also written to /root/.rackhelm-credentials with mode 600. That file is created the moment the passwords take effect, so they survive even if a later stage fails.
  3. Admin Panel Credentials — the URL https://<your host>/admin, the seeded Super Admin e-mail address, and a randomly generated 16-character password. This password is never shown again — it is redacted out of the log file.
Terminal showing the Installation Completed Successfully banner with database and admin panel credentials
Copy the Admin Panel Credentials block into your password manager before you close the terminal.

First steps after installation #

  1. Sign in at /admin with the seeded credentials and change the password and e-mail address immediately.
  2. Add the scheduler cron entry — the installer does not create one, and without it no invoices are generated and no provisioning sweeps run. See Queue workers, Horizon and the scheduler.
  3. Configure outgoing mail under Platform Settings → Mail Settings. The installer strips all MAIL_ lines from .env because mail is configured in the admin area.
  4. Move /root/.rackhelm-credentials into your password manager and delete it.

Troubleshooting #

Symptom Cause and fix
This installer must be run from the extracted release directory. The installer could not find artisan and .env.example beside itself. Change into the extracted archive and run it from there.
Composer installer checksum mismatch; refusing to run it. The download from getcomposer.org did not match the published signature. Usually a proxy or a truncated download — retry.
Cannot authenticate to MySQL as an administrator. A previous run already set the MySQL root password. Put it in ~/.my.cnf and re-run.
Database migration/seeding failed. Read /var/log/rackhelm_install_artisan.log. Usually wrong remote-database credentials or a database the user cannot create tables in.
Certificate warning at the end Certbot could not issue. Confirm DNS resolves to this server and port 80 is open, then run the certbot --nginx -d … command the installer prints.
No Admin Panel Credentials block The seeder only prints credentials when it creates the user. On a re-run against an existing database the account already exists — use the password you saved, or reset it.

For a wider list of installer error messages and what they mean, see Installation troubleshooting.

What are your Feelings