This is a boilerplate project for future use. The project consists of REST API developed by Yii2 and backend/frontend developed by Angular 6 with Bootstrap 4. Frontend project is compatible to provide server-side rendering(Angular Universal) using @ng-toolkit/universal.
The project involves:
- API
- Yii2 REST API, Yii2 RBAC, JWT (JSON Web Token), Memcached, Basic Unit & Functional Test using Codeception
- Backend: Staff/Administrator dashboard to manage staffs, users and settings
- Angular 6, Bootstrap 4, JWT (JSON Web Token), Basic Unit test using Karma+Jasmine, Moment.js, Sweet Alert, Underscore.js
- Frontend: User website to support user registration, login and account management
- Angular 6, @ng-toolkit/universal, Bootstrap 4, JWT (JSON Web Token), Basic Unit using Karma+Jasmine, Basic E2E test using Protractor+Jasmine, Moment.js, Sweet Alert
Demo
Service | Endpoint |
---|---|
Frontend | https://boilerplate.chrislee.kr |
Backend | https://boilerplate-backend.chrislee.kr |
API | https://boilerplate-api.chrislee.kr |
Architecture Diagram
Frontend - Server-side rendering (Angular Universal)
- API
- User Controller
- GET/POST/PUT/DELETE /v1/user
- POST /v1/user/login
- POST /v1/user/signup
- POST /v1/user/confirm
- POST /v1/user/password-reset-request
- POST /v1/user/password-reset-token-verification
- POST /v1/user/password-reset
- GET/POST /v1/me
- GET /v1/page/sse
- Staff Controller
- GET/POST/PUT/DELETE /v1/staff
- POST /v1/staff/login
- GET /v1/staff/get-permissions
- Setting Controller
- GET/POST/PUT/DELETE /v1/setting
- GET /v1/setting/public
- User Controller
- Backend
- Staff Login/Logout
- API generates JWT(JSON Web Token) upon successful login.
- Dashboard
- Currently, dashboard is empty page.
- Staff Management
- Admin or staff who has a permission 'manageStaffs' can create/update/delete staff information.
- Staff role can configure permissions for managing staff, user and setting.
- User Management
- Admin or staff who has a permission 'manageUsers' can create/update/delete user information.
- Setting Management
- Admin or staff who has a permission 'manageSettings' can create/update/delete setting information.
- Staff Login/Logout
- Frontend
- Support Angular Universal/server-side rendering
- User Login/Logout
- User can login with username and password.
- API generates JWT(JSON Web Token) upon successful login.
- Frontend will store JWT in local storage and use for all requests.
- API will validate submitted access token prior to process any request.
- User Registration
- User can register new account.
- API will submit verification email to the email. Note that current API system will use swift mailer component with file transport. You can check the email content in debug module.
- User Email Confirmation
- Frontend will confirm the auth key and update account status if auth key is valid.
- User Reset Password
- User can reset their password.
- API will send password reset email to the requested email.
- Frontend will display the password reset page if password reset token is valid.
- User Account
- User can change email address. If change email address, the API will send confirmation email to verify email address.
- User can change password.
Currently, the project is not ready for production use. Following steps are suitable for configuring development environment.
To run the application, you will need docker
and docker-compose
installed.
Open the console and execute following commands.
$ git clone https://github.com/chrisleekr/yii2-ngx-boilerplate.git
$ cd yii2-ngx-boilerplate
$ cp .env-dist .env
$ docker-compose up -d
With docker-compose
, following containers will be configured. Please make sure port 80, 443 are available.
- MySQL database will be configured.
- Memcached will be configured.
- REST API - Yii 2
- Database migration will be executed which are located in
/api/migrations
. - PHP-FPM and nginx will be running.
- Database migration will be executed which are located in
- Backend - Angular
- By default, development mode will be running with nginx.
- Frontend - Angular
- By default, development mode will be running with nginx.
Once all containers are finished compiling, then open the browser.
-
REST API - Yii 2: http://localhost/api/debug
- To make sure API is working, go to http://localhost/api/ping. You must see
pong
message. - To access docker container, use following command:
$ docker exec -it api /bin/sh
- To run code sniffer, use following command:
$ docker exec api composer run sniff
- To run unit test, use following command:
$ docker exec api composer run test:unit
- To make sure API is working, go to http://localhost/api/ping. You must see
-
Backend - Angular: http://localhost/backend
- Administrator username:
admin
, password:123456
- Staff username:
staff
, password:123456
- To see compile process, use following command:
$ docker logs backend --follow
- To access docker container, use following command:
$ docker exec -it backend /bin/sh
- Note that the live reloading feature has been disabled due to restriction.
- Please open Developer Tool to prevent caching. The changes will be checked every 1s. Please refer
/backend/image-files/usr/local/bin/docker-entrypoint-dev.sh
. - To run unit test, use following command:
$ cd frontend $ npm run test
- Administrator username:
-
Frontend - Angular: http://localhost/frontend
- Username:
user
, password123456
- To see compile process, use following command:
$ docker logs frontend --follow
- To access docker container, use following command:
$ docker exec -it frontend /bin/sh
- Note that the live reloading feature has been disabled due to restriction.
- Please open Developer Tool to prevent caching. The changes will be checked every 1s. Please refer
/frontend/image-files/usr/local/bin/docker-entrypoint-dev.sh
. - To run unit test, use following command:
$ cd frontend $ npm run test
- To run E2E test, use following command:
$ cd frontend $ npm run e2e
- Username:
- .env: contains environment settings
- docker-compose.yml: contains docker container specifications
- api: Yii2
image-files
: contains nginx config, php.ini, composer anddocker-entrypoint.sh
- backend: Angular Backend
image-files
: contains nginx config,docker-entrypoint-dev.sh
anddocker-entrypoint.sh
- frontend: Angular Frontend
image-files
: contains nginx config,docker-entrypoint-dev.sh
anddocker-entrypoint.sh
- nginx: Load Balancer
image-files
: contains nginx config
- Backend
- To run production mode, update
docker-compose.yml
by changingdockerfile: ./Dockerfile.dev
todockerfile: ./Dockerfile
.
- To run production mode, update
- Frontend
- To run production mode, update
docker-compose.yml
by changingdockerfile: ./Dockerfile.dev
todockerfile: ./Dockerfile
. - Note that production Dockerfile will use @ng-toolkit/universal to provide server side rendering, which means you will be able to provide compiled HTML for search engine.
- To run production mode, update
I changed backend/frontend code, but I cannot see changes in the browser.
As mentioned earlier, you have to open Developer Tool
to prevent cache if you are using Chrome. Or clear browser cache and reload again.
- Enhance user management - send confirmation email
- Enhance user authorization with Yii2 RBAC (Role Based Access Control)
- Develop new customer management section
- Apply JWT(JSON Web Token) for user authentication
- Upgrade Angular 4 to Angular 6
- Dockerize application
- Apply server side rendering for Frontend project
- [โณ] Develop more test code
- Develop file uploader