← Back to README · Documentation index

Command Usage

The main command is oro (or orobox, depending on how you installed it).

QA (qa-init, qa — sections 9 and 10) and deployment (deploy-init, ci-init, deploy — sections 13 to 15) have their own pages: QA tools and Deployment. xdebug is described in Debugging. How the commands below fit together to customize the stack is the subject of Customizing the environment.

1. Scaffolding (create)

Creates a new source tree on disk and stops. It does not touch Docker, the configuration, or the OroCommerce install — that is init’s job. The typical flow is create → cd into the new directory → init.

Scaffold a project checkout:

orobox create project my-project

This clones the public oroinc/orocommerce-application skeleton into my-project/ (no credentials needed), then removes its .git so you start with a fresh history.

Project options:

Scaffold a bundle skeleton:

cd my-project
orobox create bundle 'Acme\Bundle\FooBundle'

The argument is the bundle namespace, and where the bundle lands is read from the composer.json in the current directory. An OroCommerce application autoloads "": "src/", so inside a project checkout the command above writes src/Acme/Bundle/FooBundle/. The project already autoloads that path and Oro’s kernel discovers the generated Resources/config/oro/bundles.yml, so the bundle needs no composer.json of its own — clear the cache and it is loaded (in debug mode run orobox console cache:clear twice: the first run can leave Oro’s cached bundle list stale):

src/Acme/Bundle/FooBundle/
├── AcmeFooBundle.php
├── DependencyInjection/
│   ├── AcmeFooExtension.php
│   └── Configuration.php
└── Resources/config/
    ├── services.yml
    └── oro/bundles.yml

Run outside a PHP project — or with --standalone — and the bundle becomes its own composer package instead, in a directory named after its class, with a composer.json declaring its PSR-4 prefix and a .gitignore. That is the shape type: bundle expects, so it is where you start a bundle you intend to publish:

orobox create bundle 'Acme\Bundle\FooBundle'   # in an empty directory
cd AcmeFooBundle && orobox init

The class name is derived the way Oro derives its own — the vendor segment joined to the bundle segment, so Acme\Bundle\FooBundle gives AcmeFooBundle exactly as Oro\Bundle\UserBundle gives OroUserBundle — and the DI alias is its snake_case form (acme_foo). A fully-qualified class (Acme\Bundle\FooBundle\AcmeFooBundle) is accepted too when you want to name it yourself.

Bundle options:

No network access is required for create bundle. Both create subcommands refuse to write into a directory that already exists and is non-empty.

2. Initialization (init)

Provisions the development environment in the current directory (run it inside a directory produced by create, or an existing project/bundle checkout).

orobox init

This command:

Options:

Pre-installed database

Published Orobox images carry a dump of an OroCommerce already installed for their own version. Instead of running oro:install, init restores that dump and reconciles the schema with oro:platform:update, which reaches the same database in roughly a third of the time. The same dump is the last resort of the QA cache and of the functional test database, so a CI runner — where every cache starts empty — no longer pays for a full install on every run.

The dump holds no sample data. When ORO_SAMPLE_DATA=y (the default in .env) the demo fixtures are loaded on top of the restored database.

The dump is only used when it can be reconciled with the project it is restored into:

Anything else gets its own oro:install — as does an image built without a seed, a PostgreSQL major that did not write the dump, and any restore that does not complete. Set ORO_NO_SEED=1 to skip the dump and always install from scratch.

3. Start Environment (up)

Starts Docker containers and configures OroCommerce.

orobox up

The command regenerates the compose files, the env files and the nginx configuration from .orobox.yaml, builds the project’s image layer when one is configured and stale, and starts the services. Run it again after changing .orobox.yaml, .env, php_ini or a compose override: Compose recreates only the containers whose definition changed. When an override defines a service with a build: section, up passes --build so it is rebuilt.

Flags:

Once the stack is up, up prints the application URLs, the database connection for your IDE (host port ports.db) and, for every optional service compose actually runs, its URL and the DSN to put in your .env, all with the host ports configured in ports. Adminer runs unless services.adminer: false; RedisInsight runs with Redis and Kibana with Elasticsearch unless they are switched off. A URL whose port is 0 is not printed (the DSN hint, which works inside the stack, still is). It then lists the services your compose override advertises with the dev.orobox.url label, after the built-in blocks:

Project services:
  - minio: http://localhost:9001

The block is omitted when no service carries the label.

4. Stop Environment (down)

Shuts down the Docker services associated with the bundle.

orobox down

5. Shell Access (shell)

Opens an interactive shell in a running container, application by default: bash, or sh when the image has no bash. Any running service of the stack can be named, including the ones added by a compose override (db-test belongs to the test stack and is reachable from orobox test commands only).

orobox shell
orobox shell consumer

6. View Logs (logs)

Displays logs from different services in the development environment. At least one flag or service name must be specified.

orobox logs --app
orobox logs minio
orobox logs --nginx minio

Any compose service can be named directly, including the ones added in .orobox.compose.yaml. Services given by flag come first, then the named ones; a service mentioned twice is followed once.

Options:

7. Symfony Console (console)

Executes Symfony commands in the application container.

orobox console cache:clear

8. Run Tests (test)

Runs PHPUnit tests within the configured environment.

orobox test

Options:

11. Total Cleanup (clear)

Removes all associated containers and volumes to start from scratch. orobox clean is accepted as an alias. The named volumes declared in a compose override are removed too; see Extending the stack for keeping data across a cleanup.

orobox clear

12. Run Custom Commands (run)

Runs a custom command defined in your .orobox.yaml file.

orobox run <command-name>

Example:

orobox run otr

Options:

If you run orobox run --help, you will see a dynamic list of all commands configured in your .orobox.yaml.

16. Extending the environment (extend)

Writes the files that customize the stack, with the required headers and commented examples, so you do not have to remember the file names or the syntax.

orobox extend image             # docker/image/Dockerfile + image.dockerfile in .orobox.yaml
orobox extend compose           # .orobox.compose.yaml
orobox extend compose --local   # .orobox.compose.local.yaml (+ .gitignore entry if one exists)
orobox extend add               # list the recipes
orobox extend add varnish sftp  # add ready-made services
Command Effect
extend image Creates docker/image/Dockerfile with the ARG OROBOX_BASE_IMAGE / FROM ${OROBOX_BASE_IMAGE} header and commented examples, and sets image.dockerfile in .orobox.yaml. The Dockerfile gets a directory of its own because that directory is the build context, hashed on every container start. A file already at that path is adopted only if it is an Orobox layer (final FROM ${OROBOX_BASE_IMAGE}); otherwise the command refuses and nothing is written.
extend compose Creates .orobox.compose.yaml with commented examples: a new service with the dev.orobox.url label, an environment variable on a core service, an extra mount, and !override on ports.
extend compose --local Creates .orobox.compose.local.yaml for one developer’s own tweaks, and appends /.orobox.compose.local.yaml to .gitignore when that file exists and does not list it yet.
extend add Lists the available recipes, one name — description line each.
extend add <recipe>... Adds each recipe in order, see Recipes below. --force replaces the recipe’s services when .orobox.compose.yaml already defines them.

What the files do is described in Custom Dockerfile and Extending the stack.

Rules shared by every extend subcommand:

Recipes

A recipe is a ready-made service with everything it needs. orobox extend add <recipe> merges it into the project:

A project value always wins over a recipe value. If any part of a recipe is refused, nothing of that recipe is written. With several recipes (extend add a b) they are applied in order, and the ones before a refused recipe stay applied; the ones after it are not attempted. Images are pinned, so a recipe added today runs the same image in a year. After the receipts, each recipe prints what is left to do.

Recipe What it adds Notes printed
varnish A varnish service in front of web on http://localhost:6081 (dev.orobox.url label), with its VCL in docker/varnish/default.vcl How to point Oro’s HTTP cache invalidation (FOSHttpCacheBundle) at Varnish
selenium selenium/standalone-chrome with noVNC on http://localhost:7900 (dev.orobox.url label) The BEHAT_PARAMS / Mink settings that point Behat at it. The image’s headless Chromium stays the default; this recipe is for watching a run
sftp atmoz/sftp on port 2222 with an orobox user and a docker/sftp/upload bind mount Host, port and credentials for an integration’s SFTP settings
blackfire A blackfire agent service, image.php_extensions: [blackfire], php_ini.blackfire.agent_socket, empty BLACKFIRE_SERVER_ID / BLACKFIRE_SERVER_TOKEN in .env Where to set the credentials

Recipes publish fixed host ports (varnish 6081, selenium 7900, sftp 2222), so two projects running the same recipe at the same time collide on them. Change the port in .orobox.compose.local.yaml with ports: !override [...] for the service; the container side stays as the recipe defines it (varnish 80, selenium 7900, sftp 22), for example ports: !override ["6082:80"] for varnish.

Each recipe, what it configures and how to use it is described in Ready-made services.

When php_ini in .orobox.yaml is the path of an ini file of your own, Orobox does not edit that file: the rest of the recipe is applied, and the directives the file does not set yet are printed as lines to add to it by hand. The check runs only when the recipe is added; adding it again, with --force because its service now exists, replaces the service with the recipe’s and reports nothing left to do once the directives are in the file.

17. Test Environment (test-init)

Creates, or resets, the test database that orobox test runs against: starts db-test (plus Redis, RabbitMQ, Elasticsearch and Mailpit when they are enabled), drops the test database and installs OroCommerce in the test environment.

orobox test-init
orobox test-init --tmpfs --tmpfs-size 2g

When the test database is already installed, it asks before resetting it. At the end it prints the connection details of the test database, with the host port configured as ports.db_test (default 5433).

Options:

18. Database Backup and Restore (db)

Dumps the development database to a file, or loads one back.

orobox db backup var/backup.sql
orobox db restore var/backup.sql

19. Update Orobox (self-update)

Replaces the running binary with the latest release for your platform. When a newer release was installed, it then pulls the newer versions of the published Orobox images you have locally.

orobox self-update

A project’s image layer is not rebuilt by self-update; the next command that starts containers notices the new base image and rebuilds it.