Install Scriptor

What this covers

Getting a Scriptor instance running from zero. Three paths are covered:

  • Docker quickstart when you want to see Scriptor without installing PHP, Composer, or SQLite locally.
  • Native install when you have PHP 8.2+ and Composer on the machine and want a normal dev or production setup.
  • Shared hosting when the webroot is fixed (e.g. public_html/) and you cannot move Scriptor's source code outside it.

Pick one path and follow it through to the "what to check after" section. The other paths are alternatives, not steps.

Walkthrough

Path 1: Docker quickstart

If you just want to try Scriptor, this is the fastest route. Docker is the only prerequisite.

git clone https://github.com/bigin/Scriptor.git
cd Scriptor
docker compose up -d --build

The stack listens on http://localhost:8080/. Open it in a browser; you should see a Home page with the default theme.

The editor is at http://localhost:8080/editor/. Log in with admin / gT5nLazzyBob (the bundled demo password). The first thing the first boot topic tells you to do is change that password.

If port 8080 is already taken (ServBay, another container, a local app) override the host-side port:

SCRIPTOR_DEMO_PORT=8090 docker compose up -d --build

The container itself always binds 80; only the host port changes.

For a private demo with your own password instead of the documented one:

SCRIPTOR_ADMIN_PASSWORD='your-strong-secret' \
  SCRIPTOR_DEMO_PORT=8090 \
  docker compose up -d --build

This image is built for exploration: one PHP container plus one nginx container, SQLite database baked into the image, no persistent volumes by default. It is not a production deployment. For the long-form rationale and a full list of what the seed creates, see docs/demo.md in the Scriptor repo.

Path 2: Native install

PHP 8.2+ with the standard extensions, Composer 2, SQLite 3.38+:

git clone git@github.com:bigin/Scriptor.git
cd Scriptor
composer install
php bin/scriptor install

The install command:

  1. Confirms the database path. Type INSTALL and press Enter.
  2. Prompts for an admin password (8 characters minimum, echo suppressed) and asks you to confirm it.
  3. Creates the Pages and Users categories with their fields, seeds an admin user, and adds a Home page.

You should see four [n/4] progress lines and a summary block with the editor URL.

Point your web server at the public/ directory and visit /. For PHP's built-in server during local development:

php -S 127.0.0.1:8080 -t public public/index.php

For non-interactive installs (CI, scripted provisioning, the Docker entrypoint) pass --yes and supply the password through the SCRIPTOR_ADMIN_PASSWORD environment variable:

SCRIPTOR_ADMIN_PASSWORD='your-strong-secret' \
  php bin/scriptor install --yes

The command refuses to run a second time once installed, so leaving it in a provisioning script is safe.

Path 3: Shared hosting (fixed webroot)

When the hosting environment puts your webroot at a fixed path like public_html/, you cannot place Scriptor's source code outside it the way the native install does. The shared-hosting path bundles public/ contents with the rest of the source under that fixed root, then uses a .htaccess rule to keep everything that is not under public/ invisible to the web.

The walkthrough is in docs/install-shared-hosting.md in the Scriptor repo. The short version:

  1. Upload the Scriptor source via SFTP into a directory inside public_html/ (for example public_html/scriptor/).
  2. Run composer install over SSH if your host allows it, or upload vendor/ produced on your local machine.
  3. Run php bin/scriptor install --yes over SSH, or run it locally against the production database path and upload data/imanager.db separately.
  4. Point the site's domain alias at public_html/scriptor/public/ if the host allows per-domain document roots; otherwise use the bundled .htaccess rules in public_html/.htaccess to route everything to public_html/scriptor/public/index.php.

If your host does not allow SSH or symlinks, the Docker path is not an option and the shared-hosting path is the only route. If your host does allow SSH and a custom document root, the native path is simpler.

What to check after

A successful install means all of these are true:

  • / (or http://localhost:8080/ for Docker) returns HTTP 200 and renders the Home page in the default theme.
  • /editor/ (or http://localhost:8080/editor/) shows a login form, not a 404.
  • The credentials you set during install (or the documented demo credentials for the Docker path) let you in.

If any of those fail, jump to the troubleshooting section.

Troubleshooting

Browser shows a directory listing or "It works!" instead of Scriptor

The web server is serving the wrong directory. Point it at the public/ subdirectory of the Scriptor checkout, not the repo root. For the Docker quickstart, this is handled by the bundled compose stack; if you replaced it with your own, double-check the volume and the document-root path.

"Category with slug 'pages' not found" when you visit /

You started the web server before running php bin/scriptor install. The install command seeds the schema; the web server alone never does. Stop the server, run the install command, then start the server again.

bin/scriptor install refuses with "Refusing to proceed: stdin is not a TTY"

You ran the command from a non-interactive context (CI script, Docker entrypoint, nohup). Add --yes and supply the password through SCRIPTOR_ADMIN_PASSWORD or --password. The confirmation prompt only runs when a human is at the keyboard.

bin/scriptor install rejects your password with "too short"

The minimum is 8 characters, matching iManager's PasswordFieldType. There is no override; pick a longer one. A short list of obvious defaults (password, admin, 12345678, etc.) is also rejected.

See also