README

Get started quickly with an USM enabled Yii2 project.

Published under MIT license.

Features

Ultimate Site Management pre-configured.
DotEnv for management of environment variables.
Docker-compose with
- PHP container running your Yii2 application
- MariaDB container with database stored in local ./runtime/database folder
- Mailpit, a mail debugging tool
Devcontainer for easy development in VS Code.

Prerequisites

Make sure the following programs are installed on your computer:

Installation

You can create your own project based on the USM Starter template using the following command (replace my-app-name with the name you want to name your project):

docker run -u "$(id -u):$(id -g)" --rm -v $PWD:/app composer create-project --prefer-dist maerduq/usm-starter my-app-name

The command starts a docker container to run the composer create-project command. This command creates your project files based on USM Starter.

Getting started for local development

With devcontainer

$ cp .env-dev.example .env - to setup you environment variables file.
Open the project folder in VS Code. VS Code will give a pop-up with a button "Reopen in Container". Click that.

Without devcontainer

$ cp .env-dev.example .env - to setup you environment variables file.
$ docker-compose up -d - to start your docker containers.
$ docker-compose exec -T app bash composer run setup-dev - for quick setup (run in your php container)

First setup of USM User module

UMS is by default configured to use the USM user module. To create the first user of your website, execute the following command:

php yii usm/user/create {name} {email}

What's running

Now visit your website on http://localhost:8000/
PHPMyAdmin (for managing your database) on http://localhost:8001/
A very useful mail debugger called mailpit is available on http://localhost:8025/
And your MariaDB server is accessible via localhost:3006

Getting started for production

$ cp .env-prod.example .env - to setup you environment variables file.
Edit the values in .env to your preference.
$ ./deploy - to install everything.

Other available bash scripts

[!NOTE] When not using devcontainers, before running any command, run $ docker-compose exec -it app bash to start an interactive bash session in your Yii2 application docker container.

# composer run watch - for watchers used during development
# composer run generate-i18n - generate translation files from your views. Learn more.

Application configuration

Change the environment variables as you like using the explanation of the variables below.

Variables

Name	Description
YII_DEBUG	Whether Yii should run in debug mode (1 or 0)
YII_ENV	The Yii environment setting to run (dev, test, or prod)
DB_HOST	Host name of your database (e.g. localhost)
DB_NAME	Name of your database
DB_USERNAME	Username to access your database
DB_PASSWORD	Password to access your database
DB_CHARSET	Charset of your database (e.g. utf8mb4)
DB_SCHEMA_CACHE	Whether the schema of your database should be cached
Mail settings	---
ADMIN_EMAIL	The administrator's email
SENDER_EMAIL	The email address used as "from" when the website sends mails
SENDER_NAME	The name used as "from" when the website sends mails
MAIL_HOST	The host name of the SMTP mail server
MAIL_PORT	The port of the SMTP mail server
MAIL_USERNAME	The username with which to authenticate on the SMTP mail server
MAIL_PASSWORD	The password with which to authenticate on the SMTP mail server
MAIL_ENCRYPTED	Whether the connection with the SMTP mail server is encrypted
MAIL_TO_FILE	Whether to use the mail-to-file feature (writes sent mails to a file in `runtime/mail`)
Docker settings	---
PHP_VERSION	The PHP version used for the docker PHP container
UID	The Linux uid used for running the docker container (default: 1000)
GID	The Linux gid used for running the docker container (default: 1000)
APP_PORT	The port on which to access the USM application (default: 8000)
DATABASE_PORT	The port on which to access the MariaDB database (default: 3306)
PHPMYADMIN_PORT	The port on which to access the PHPMyAdmin application (default: 8001)
MAILPIT_PORT	The port on which to access the PHPMyAdmin application (default: 8001)

Directory Structure

  assets/             contains assets definition
  commands/           contains console commands (controllers)
  config/             contains application configurations
  controllers/        contains Web controller classes
  models/             contains model classes
  runtime/            contains files generated during runtime
  vendor/             contains dependent 3rd-party packages
  views/              contains view files for the Web application
  web/                contains the entry script and Web resources

Contributors

Paul Marcelis

Testing