creative-commoners / create-ss-demo
Creates demo sites from the current working directory
Installs: 5
Dependents: 0
Suggesters: 0
Security: 0
Stars: 2
Watchers: 2
Forks: 0
Open Issues: 4
Type:project
Requires
- php: >=7.1.0
- guzzlehttp/guzzle: ^6.3
- symfony/console: ^3.0 || ^4.0
- symfony/filesystem: ^3.0 || ^4.0
- symfony/process: ^3.0 || ^4.0
Requires (Dev)
- phpunit/phpunit: ^7.5
- squizlabs/php_codesniffer: ^3.4
This package is auto-updated.
Last update: 2024-10-14 09:15:30 UTC
README
A command line utility that creates demo sites using the SilverStripe Platform API.
Requirements
- PHP ^7.1
- Docker to create containers
- A Docker Hub account to store the container tags
- SilverStripe Platform stack permissions for the content snapshots
- sspak to create snapshots
Installation
Install globally with Composer:
composer global require creative-commoners/create-ss-demo dev-master
Ensure the global Composer bin folder is in your system path.
Configuration
Ensure you have logged into your Docker Hub account:
docker login
You will also need to have set up a SilverStripe Platform API token (which can be done through the "My profile" section) and have it defined in environment variables:
SS_DEMO_AUTH_USER
: your SSP email addressSS_DEMO_AUTH_KEY
: your SSP API token
Ensure you don't commit these into any codebases anywhere.
Usage
You have a local environment ready to share with someone, and you want to publish it. The steps involved are:
- Build and publish (
build
) a Docker container - Create (
instantiate
) the demo instance - Destroy (
destroy
) the demo instance once finished with it
Building the Docker container
You don't need to have Docker enabled for your project, this tool will copy the necessary Docker configuration files into your project in order to build it into an image. You can then delete the files manually, or leave them there. At some point this will be automated as well.
To build the container, run create-ss-demo build
with the following arguments:
name
: The name for your image, e.g. "sprint-2019-01-02"username
: Your Docker Hub username, e.g. "johnsmith"version
: The version to tag the image with, e.g.0.1
create-ss-demo build sprint-2019-01-02 johnsmith 0.1
This will build a Docker image with the specified name, tag it as the specified version, and push it to Docker Hub under the specified username.
Custom environment variables
If your demo site image needs to have custom environment variables defined in it, add them to a .env
file in the
project's folder you're building. These will be merged with the default container environment variables when
the SilverStripe application runs.
# File: .env
FOO=BAR
Important: Your Docker image will need to be public on Docker Hub in order for SilverStripe Platform to access
and use it for demo builds. For this reason, ensure you do not include any sensitive data in your .env
file.
Only use mocked values and do not store any API keys, etc.
Create the demo instance
Once you have a Docker container, you can ask SilverStripe Platform to build a demo environment with it. You will also need a sspak snapshot which will need to be uploaded to a SilverStripe Platform stack via the "Snapshots" section. Once this is complete, you will need to obtain the numeric ID for it from the "Snapshots" section.
To request a demo instance, run create-ss-demo instantiate
with the following arguments:
site_name
: The site name used for the demo subdomain, e.g.johnsmithsprint1
(cannot contain dashes etc)image
: The Docker Hub image name and tag/version, e.g. "johnsmith/sprint-2019-01-02:01"stack_name
: The SilverStripe platform stack code, e.g.mystack
snapshot_id
: The sspak snapshot ID from SilverStripe platform to use for content, e.g. 12846
create-ss-demo instantiate johnsmithsprint1 johnsmith/sprint-2019-01-02:0.1 mystack 12846
The SilverStripe Platform API will start processing your request, and the command will poll occasionally and provide the command with status updates. Once complete, you will be given the demo site URL and username/password to log into it. This can now be shared with other people.
Note: You will need to have necessary permissions on the specified SilverStripe Platform stack in order to perform this action.
Destroying demo sites
Once your demo environment is no longer required you should close it down to prevent wasting AWS resources. To do this
you can run create-ss-demo destroy
with the following arguments:
demo_id
: The demo site ID to destroystack_name
: The SilverStripe platform stack code, e.g.mystack
create-ss-demo destroy 1123 mystack
Note: You will need to have necessary permissions on the demo's original SilverStripe Platform stack in order to perform this action.