Skip to content
/ ootstra Public

ootstra ss an opinionated set of tools for a ready to run, build & deploy Silverstripe CMS instance with elemental

License

BSD-4-Clause license
8 stars 0 forks Branches Tags Activity
Star
Notifications You must be signed in to change notification settings

lerni/ootstra

BranchesTags

Repository files navigation

Status - WIP

This is work in progress!

Setup, Requirements & Install

"ootstra" is inspired by Bigfork’s quickstart recipe for Silverstripe. It's an opinionated set of tools for a ready to run, build & deploy a CMS instance. To get it up and running you'll need GIT, an editor like VSCode (recommended) & ddev. It utilizes dnadesign/silverstripe-elemental for a block/element based CMS experience and comes with the following set of elements:

  • ElementContent
  • ElementForm (userforms)
  • ElementVirtual
  • ElementHero (Slider, YouTube Video)
  • ElementMaps (Google)
  • ElementPerso (URLs Perso, vCard)
  • ElementPersoCFA (linked persos)
  • ElementContentSection (accordion with FAQ schema)
  • ElementCounter
  • ElementLogo (partner/sponsor)
  • ElementGallery (lightbox, slider)
  • ElementTeaser
  • ElementFeedTeaser (holder concept with multiple parents & filtering per tags)
  • ElementTextImage
  • ElementPDFDocument PDF Download with preview & description

Optional, separate modules/elements:

  • InstagramFeed
  • ElementJobs lerni/jobpostings (privat), schema.org & sitemap.xml integration
  • lerni/simplebasket (privat), Google Shoppingfeed with local Inventory, swissQR bill and CAMT payment reconciliation or Datatrans Payments

Other features:

Getting started

Per .vscode/extensions.json extensions 'll be suggested. .vscode/settings.json makes Logviewer work and contains settings for debugging etc.

clone or fork lerni/ootstra

    git clone [email protected]:lerni/ootstra.git "PROJECT"

On the first request database structure 'll automatically be generated - it runs dev/build. Before you do so, set the correct default locale in app/_config.php like:

    i18n::set_locale('de_CH');

ddev/Docker dev-env

By default foldername is used as projectname, this is recommended because .vscode/launch.json uses ${workspaceFolderBasename}. Run ddev config in the project directory. Now you're ready to run ddev start & ddev composer i. This provides a webserver at https://PROJECTNAME.ddev.site, phpMyAdmin at https://PROJECTNAME.ddev.site:8037, and Mailpit at https://PROJECTNAME.ddev.site:8026/. Default login at /admin is admin & password.

npm, Laravel Mix watch & build etc.

Laravel Mix (webpack based) is used as build environment. You need to run ddev theme install to install npm packages. Watcher browsersync/reload can be started with ddev theme watch and 'll be available at https://PROJECTNAME.ddev.site:3000/. A production build can be done with ddev theme prod. See also scripts section in themes/default/package.json and Mix CLI.

VSCode tasks - remember all the commands 💁

There are a bunch of tasks in .vscode/tasks.json available per Command+Shift+B:

  • ddev start (magenta)
  • ddev stop (magenta)
  • ddev restart (magenta)
  • composer install (magenta)
  • composer update (magenta)
  • composer vendor-expose (blue)
  • ddev log web (magenta)
  • ddev theme install (green)
  • ddev theme watch (green)
  • ddev theme prod (green)
  • flushh (blue - flush hard) instead of ddev exec rm -rf ./silverstripe-cache/*
  • dev/build (blue) instead of ddev php ./vendor/silverstripe/framework/cli-script.php dev/build flush
  • ssshell (blue) instead of ddev php ./vendor/bin/ssshell
  • download database from live (cyan)
  • download assets from live (cyan)
  • ssh test / live (cyan)
  • deploy test / live (cyan)
  • deploy:unlock test / live (cyan)
  • xdebug on / off (magenta)
  • dep releases test / live (cyan)

Colors group tasks like:

  • magenta: local ddev
  • blue: local silverstripe specific
  • green: local npm
  • cyan: remote server

Database, credentials etc. are provided as environment-variables from .ddev/config.yaml and are populated in /.env during DDEV-start. Project specific / sensitive env-vars should be set in /.env and won't land in GIT. For example you do not have to setup DB credentials for dev environment to work, but you need to set APP_GOOGLE_MAPS_KEY, SS_NOCAPTCHA_SITE_KEY & SS_NOCAPTCHA_SECRET_KEY in .env order to make Google Maps & reCaptcha work.

PHP Version

Current used PHP-Version is 8.3. It's set in following places:

  • .ddev/config.yaml
  • deploy/config.php
  • public/.htaccess -> watch out if stage specific versions are maintained in deploy/
  • composer.json
  • .vscode/settings.json

Don't forget to ddev restart and update packages ddev composer u after changing!

Hosting & Deployment

Deployment is based on Deployer, a php based cli-tool, which is included as dev-requirement per composer.json. It uses symlinks to the current release. It's easy to use, offers zero downtime deployments and rollback. /assets, .env are shared resources, this means they are symlinked into each release-folder. On remote servers you'll need SSH & git, composer, same php-version on CLI as httpd, ln, readlink, realpath, rsync, sed & xargs.

~/public_html/0live     or ~/public_html/0test
|
|--.dep
|  |--releases          deployers internal notes
|
|--current              -> ~/public_html/0live/releases/3 for example
|  |--.env              -> ~/public_html/0live/shared/.env
|  |--...               all the files from repo & vendors
|  |--public            actual webroot but symlinked per parent-dir (current)
|  |  |--assets/        -> ~/public_html/0live/shared/assets
|
|--releases
|  |--1
|  |  |--.env           -> ~/public_html/0live/shared/.env
|  |  |--...
|  |
|  |--2
|  |  |--.env           -> ~/public_html/0live/shared/.env
|  |  |...
|  |
|  |--...               as many as defined in keep_releases
|
|--shared
   |--public/assets
   |--.env

You need to add your public key on remote servers in ~/.ssh/authorized_keys. On nix-based systems you can use ssh-copy-id to do so.

Configuration

Rename config.example.php to deploy/config.php and configure things to your needs. Usually .htaccess in public comes from the repo but if needed, it can be overwritten with a stage specific version. Just create ./deploy/test.htaccess or ./deploy/live.htaccess, which than 'll overwrite public/.htaccess during deployment according to the stage in use.

Deploy

Key-forwarding is used, allowing deployment to be done from inside ddev-web container. Run ddev auth ssh to have it available. Before first deployment, SSH into remote servers like ddev php ./vendor/bin/dep ssh test or ddev php ./vendor/bin/dep ssh live and ensure SSH fingerprint from the git-repo is accepted. You may just do a git clone into a test directory to verify everything works as expected. If so, deployment is done as follows:

    ddev php ./vendor/bin/dep deploy test

or

    ddev php ./vendor/bin/dep deploy live

The first time you deploy to a given stage, you’ll be asked to provide database credentials etc. to populate .env. A file similar as below 'll be created.

# For a complete list of core environment variables see
# https://docs.silverstripe.org/en/4/getting_started/environment_management/#core-environment-variables

# APP_GOOGLE_MAPS_KEY=''
# SS_NOCAPTCHA_SITE_KEY=''
# SS_NOCAPTCHA_SECRET_KEY=''

# Environment dev/stage/live
SS_ENVIRONMENT_TYPE='dev'
# SS_BASE_URL=''

# SS_DEFAULT_ADMIN_USERNAME=''
# SS_DEFAULT_ADMIN_PASSWORD=''

SS_ERROR_EMAIL=''
SS_ADMIN_EMAIL=''

## Database {#database}
SS_DATABASE_NAME='db'
# SS_DATABASE_CHOOSE_NAME=true
SS_DATABASE_CLASS='MySQLDatabase'
SS_DATABASE_USERNAME='db'
SS_DATABASE_PASSWORD='db'
SS_DATABASE_SERVER='db'
SS_DATABASE_PORT='3306'

SS_ERROR_LOG='silverstripe.log'

GHOSTSCRIPT_PATH='/usr/bin/gs'

SCRIPT_FILENAME=''

See also:

https://www.silverstripe.org/learn/lessons/v4/up-and-running-setting-up-a-local-silverstripe-dev-environment-1

Deploy a branch/tag/revision

# Deploy revision (git SHA) to test
ddev php ./vendor/bin/dep deploy --revision=ca5fcd330910234f63bf7d5417ab6835e5a57b81 test

# Deploy dev branch to test
ddev php ./vendor/bin/dep deploy --branch=dev test

# Deploy tag 1.0.1 to live
ddev php ./vendor/bin/dep deploy live --tag=1.0.1 live

Show deployed revision

ddev php ./vendor/bin/dep releases live

task releases
+----------------------+-------------+-------- live ---+------------------------------------------+
| Date (Europe/Zurich) | Release     | Author | Target | Commit                                   |
+----------------------+-------------+--------+--------+------------------------------------------+
| 2022-11-21 16:57:41  | 1           | user   | HEAD   | 089d9397c34f0c478059a09470000006ed41e000 |
| 2022-12-01 16:06:45  | 2           | user   | HEAD   | 007300b9e054675050d0d1de7000000444918000 |
| 2022-12-02 10:41:18  | 3 (current) | user   | HEAD   | 0d2f7df3fbbc53f666366c3cf000000a392f3000 |
+----------------------+-------------+--------+--------+------------------------------------------+

... or use VSCode tasks Command+Shift+B

Uploading/downloading database from live/test

# Upload database to test
ddev php ./vendor/bin/dep silverstripe:upload_database test

# Download database from live
ddev php ./vendor/bin/dep silverstripe:download_database live

etc.
or use VSCode tasks Command+Shift+B

Uploading/downloading assets from live/test utilizing rsync

# Download assets from live
dep silverstripe:download_assets live

# Upload assets to test
dep silverstripe:upload_assets test

etc.
or use VSCode tasks Command+Shift+B

Manual remote dev/build

DevelopmentAdmin over HTTP is disabled in Live-Mode per yml-config. Following deployer-tasks 'll do.

# dev/build on live
ddev php ./vendor/bin/dep silverstripe:dev_build live -v
# dev/build on test
ddev php ./vendor/bin/dep silverstripe:dev_build test -v

License

ootstra is licensed under the BSD license. Third-party modules have different licenses like (0BSD, Apache 2.0, Apache-2.0, BSD*, BSD-2-Clause, BSD-3-Clause, CC-BY-3.0, CC-BY-4.0, CC0-1.0, GPL-2.0, GPL-3.0+, GPL-3.0-or-later, ISC, MIT, MIT*, Zlib, etc.). Check with composer licenses, npx license-checker --summary in themes/default and be aware of the suggested plugins for VSCode. Use implies acceptance of all licenses. Note that @fancyapps/ui is commercial software requiring a purchased license.

About

ootstra ss an opinionated set of tools for a ready to run, build & deploy Silverstripe CMS instance with elemental

Topics

cms silverstripe boilderplate

Resources

Readme

License

BSD-4-Clause license
Activity

Stars

8 stars

Watchers

5 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

No packages published

Languages