added documentation

README.md

@@ -1,75 +1,151 @@
 ## Laravel 5-5 example ##
 
-**Laravel 5-5 example** is a tutorial application.
-
-### Installation ###
-
-* type `git clone https://github.com/bestmomo/laravel5-5-example.git projectname` to clone the repository 
-* type `cd projectname`
-* type `composer install`
-* type `composer update`
-* copy *.env.example* to *.env*
-* type `php artisan key:generate`to generate secure key in *.env* file
-* if you use MySQL in *.env* file :
-   * set DB_CONNECTION
-   * set DB_DATABASE
-   * set DB_USERNAME
-   * set DB_PASSWORD
-* if you use sqlite :
-   * type `touch database/database.sqlite` to create the file
-* type `php artisan migrate --seed` to create and populate tables
-* edit *.env* for emails configuration
-
-### Include ###
-
-* [Styleshout](https://www.styleshout.com/) for front template
-* [CKEditor](http://ckeditor.com) the great editor
-* [Elfinder](https://github.com/Studio-42/elFinder) the nice file manager
-* [Sweat Alert](http://t4t5.github.io/sweetalert/) for the cool alerts
-* [AdminLTE](https://adminlte.io/themes/AdminLTE/index2.html) the great admin template
-* [Gravatar](https://github.com/creativeorange/gravatar) the Gravatar package
-* [Intervention Image](http://image.intervention.io/) for image manipulation
-* [Email confirmation](https://github.com/bestmomo/laravel-email-confirmation) the package for email confirmation
-* [Artisan language](https://github.com/bestmomo/laravel-artisan-language) the package for language strings management
-* [Laravel debugbar](https://github.com/barryvdh/laravel-debugbar)
-* [Etrepat baum](https://github.com/etrepat/baum) for comments management
-
-### Features ###
-
-* Home page
-* Custom error pages 403, 404 and 503
-* Authentication (registration, login, logout, password reset, mail confirmation, throttle)
-* Users roles : administrator (all access), redactor (create and edit post, upload and use medias in personnal directory), and user (create comment in blog)
-* Blog with nested comments
-* Search in posts
-* Tags on posts
-* Contact us page
-* Admin dashboard with users, posts, articles, medias, settings, notifications and comments
-* Multi users medias gestion
-* Localization (English, French and Chinese)
-* Application tests
-* Thumbs creation for images
-* Notifications to send emails and notify redactors for new comments
-
-### Tricks ###
-
-To use application the database is seeding with users :
-
-* Administrator : email = [email protected], password = admin
-* Redactor : email = [email protected], password = redac
-* User : email = [email protected], password = walker
-* User : email = [email protected], password = slacker
-
-### Tests ###
-
-When you want to launch the tests refresh and populate the database :
-
-`php artisan migrate:fresh --seed`
-
-You must have default settings and **en** language. You must also add provider in **config/app.php**.
-
-You can then use Dusk.
-
-### License ###
-
-This example for Laravel is open-sourced software licensed under the MIT license
+**Laravel 5-5 example** is a tutorial application showing how to run and maintain laravel on kubernetes. It will allow you to quickly get a database and SSL-enabled wepage working within 10 minutes which can then be tailored to your requirements.
+
+Suggested improvements are welcome as are PRs. There isn't much available online for laravel + kubernetes together, however this presentation is probably the best material <https://www.slideshare.net/WilliamStewart20/kubernetes-laravel-and-kubernetes> and the following tutorial from Bitnami is useful also <https://docs.bitnami.com/kubernetes/how-to/deploy-php-application-kubernetes-helm/>.
+
+## Prerequisities ##
+This tutorial assumes you have access to a cloud-based cluster with kubernetes v1.9 or higher (e.g. GKE, ACS-engine or AWS - Google Kubernetes Engine is the easiest to setup). A domain URL and ability to change DNS A records is also assumed. Nginx-ingress for tls termination is used.
+Helm (`brew install kubernetes-helm` >v2.8.2) and kubectl (`brew install kubectl` >1.9.3) are assumed to be installed and pointing at your cluster. A common pitfall for new users to helm is Role-Based-Access-Control, so if you're new to helm, you should give helm the required access with `kubectl apply -f kubernetes/kubernetes-yaml/rbac-tiller.yaml` and then use `helm init --service-account tiller`.
+
+
+## Installation ##
+
+```bash
+git clone https://github.com/EamonKeane/larvel5-5-example
+```
+
+```bash
+cd laravel5-5-example
+```
+
+* check that  helm and kubectl are on the right versions on the server and locally
+
+```bash
+helm version
+Client: &version.Version{SemVer:"v2.8.2", GitCommit:"a80231648a1473929271764b920a8e346f6de844", GitTreeState:"clean"}
+Server: &version.Version{SemVer:"v2.8.2", GitCommit:"a80231648a1473929271764b920a8e346f6de844", GitTreeState:"clean"}
+```
+
+```bash
+kubectl version
+Client Version: version.Info{Major:"1", Minor:"9", GitVersion:"v1.9.3", GitCommit:"d2835416544f298c919e2ead3be3d0864b52323b", GitTreeState:"clean", BuildDate:"2018-02-09T21:51:54Z", GoVersion:"go1.9.4", Compiler:"gc", Platform:"darwin/amd64"}
+Server Version: version.Info{Major:"1", Minor:"9+", GitVersion:"v1.9.4-gke.1", GitCommit:"10e47a740d0036a4964280bd663c8500da58e3aa", GitTreeState:"clean", BuildDate:"2018-03-13T18:00:36Z", GoVersion:"go1.9.3b4", Compiler:"gc", Platform:"linux/amd64"}
+```
+
+* Specify your domain:
+
+```bash
+MY_URL=laravel2.squareroute.io # change this to your domain
+```
+
+* If you don't already have nginx-ingress installed on your cluster, install it:
+
+```bash
+helm install stable/nginx-ingress --name nginx-ingress --namespace laravel5
+```
+
+* Add your nginx-ingress IP address as a DNS A record pointing to your laravel URL:
+
+```bash
+INGRESS_IP=$(kubectl get svc --namespace laravel5 -o json | jq .items[0].status.loadBalancer.ingress[0].ip)
+```
+
+* Verify that it has updated
+
+```bash
+dig $MY_URL
+...
+;; ANSWER SECTION:
+laravel2.squareroute.io. 5      IN      A       35.230.155.177
+...
+```
+
+Install Cert-Manager for automatic SSL provisioning. <https://github.com/kubernetes/charts/tree/master/stable/cert-manager>
+
+```bash
+helm install stable/cert-manager --name cert-manager --namespace laravel5 --set ingressShim.extraArgs='{--default-issuer-name=letsencrypt-prod,--default-issuer-kind=ClusterIssuer}','extraArgs={--v=4}'
+```
+
+```bash
+kubectl apply -f kubernetes/helm/cert-manager/acme-prod-cluster-issuer.yaml
+```
+
+* Install the mysql database with preconfigured password:
+
+```bash
+helm install stable/mysql --wait --timeout 400 --name mysql --namespace laravel5 --set mysqlRootPassword=imApMsfoDt,mysqlDatabase=homestead
+```
+
+* Make repository for the nginx and phpfpm dockerfiles (skip to the `Replace URL` section to use the images already built):
+
+```bash
+MY_PHP_REPO=quay.io/eamonkeane/laravel
+MY_NGINX_REPO=quay.io/eamonkeane/laravel-nginx
+```
+
+* Build and push the docker images. This tutorial assumes the respositories are publicly accessible.
+
+```bash
+docker build . -t ${MY_PHP_REPO}:latest -f docker/php-fpm/Dockerfile; docker push {MY_PHP_REPO}:latest
+```
+
+```bash
+docker build . -t ${MY_NGINX_REPO}:latest -f docker/nginx/Dockerfile; docker push {MY_NGINX_REPO}:latest
+```
+
+* Replace the images in the helm chart with the ones you have built:
+
+```bash
+sed -i '' -e "s#quay.io/eamonkeane/laravel#${MY_PHP_REPO}#g" kubernetes/helm/laravel5/values.yaml
+```
+
+```bash
+sed -i '' -e "s#quay.io/eamonkeane/laravel#${MY_NGINX_REPO}#g" kubernetes/helm/laravel5/values.yaml
+```
+
+* Replace the URL in the .env with your url. Note the .env is kept in the helm folder for convenience to make the secret as part of this tutorial. If using this for production, make the secrets separately using `kubectl create secret generic ${SECRET_NAME} --from-file=${SECRET_FILE}` or use a tool to encrypt the secrets such as helm secrets: <https://github.com/futuresimple/helm-secrets>.
+
+```bash
+sed -i '' -e "s#https://laravel2.squareroute.io#https://${MY_URL}#g" kubernetes/helm/laravel5/laravel5-env.env
+```
+
+* Install laravel5. This will seed the mysql database before creating the php containers using a pre-install job.
+
+```bash
+helm upgrade --install --wait --timeout 400 --namespace laravel5 laravel5 kubernetes/helm/laravel5
+```
+
+* After approximately 2 minutes the website will be visible at `https://${MY_URL}`
+
+![laravel landing page](docs/laravel-home-page.png)
+
+For changes to the repository, the same command can be run again. This time it will not perform a database seed, but will only perform the migrations before installing the new pods.
+
+```bash
+helm upgrade --install --wait --timeout 400 --namespace laravel5 laravel5 kubernetes/helm/laravel5
+```
+
+## Cleaning Up ##
+
+This will delete everything created by the above tutorial but leave everything else in your cluster as it was.
+
+```bash
+`kubectl delete namespace laravel5`
+```
+
+The helm chart contains the following features which are relevant to laravel:
+
+* Logs are tailed to standard out from the `/storage/logs/laravel.log` in keeping with Kubernetes best practice
+
+* PHP-FPM is PID 1 in the php container
+
+* Migrations and seeding are performed as pre-install jobs and upgrades. It is possible to manage these outside of the helm chart (for example as part of a CI/CD workflow, to run a job before running `helm upgrade`). See the discussion here <https://github.com/kubernetes/helm/issues/2243> and here <https://blog.bigbinary.com/2017/06/16/managing-rails-tasks-such-as-db-migrate-and-db-seed-on-kuberenetes-while-performing-rolling-deployments.html>
+
+* Configuration files (nginx.conf and laravel-site.conf) are kept in the helm folder (helm can't access files outside this folder) and the configmap is updated each time the deployment is triggered.
+
+* Configmap changes to nginx trigger an upgrade of the nginx deployment
+
+* Nginx and PHP as separate deployments to allow for independetly scaling the number of replicas. It is also possible to have these as multiple containers in the same pod.
+
+As mentioned, improvements are welcome.

docker/php-fpm/Dockerfile

@@ -1,17 +1,18 @@
 FROM php:7.2-fpm
 
-#--------------------------------------------------------------------------
-# Software Installation
-#--------------------------------------------------------------------------
-# Installing tools and PHP extentions using "apt", "docker-php", "pecl",
-#
-
-# Install "curl", "libmemcached-dev", "libpq-dev", "libjpeg-dev",
-#         "libpng-dev", "libfreetype6-dev", "libssl-dev", "libmcrypt-dev",
+MAINTAINER Eamon Keane <[email protected]>
 
+ARG VCS_REF
+ARG BUILD_DATE
 ARG PROJECT=laravel5
 ARG DOCKERFILE_DIR=docker/php-fpm
 
+# Metadata
+LABEL org.label-schema.vcs-ref=$VCS_REF \
+      org.label-schema.vcs-url="https://github.com/EamonKeane/laravel5-5-example" \
+      org.label-schema.build-date=$BUILD_DATE \
+      org.label-schema.docker.dockerfile="/docker/php-fpm/Dockerfile"
+
 RUN apt-get update \
   && apt-get install -y --no-install-recommends \
     cron \
@@ -61,23 +62,21 @@ COPY . /var/www/${PROJECT}
 
 RUN composer dump-autoload --optimize;
 
-#COPY ${DOCKERFILE_DIR}/entrypoint-migrate.sh entrypoint.sh
 COPY ${DOCKERFILE_DIR}/entrypoint.sh entrypoint.sh
 
 RUN chmod +x entrypoint.sh
 
 # Create the Laravel Log file and assign it to www-data:
-RUN mkdir -p /var/www/${PROJECT}/storage/logs
-RUN touch /var/www/${PROJECT}/storage/logs/laravel.log
-RUN chown www-data:www-data /var/www/${PROJECT}/storage/logs/laravel.log
+RUN mkdir -p /var/www/${PROJECT}/storage/logs && \
+    touch /var/www/${PROJECT}/storage/logs/laravel.log && \
+    chown www-data:www-data /var/www/${PROJECT}/storage/logs/laravel.log
 
 #Make storage folder and give access to www-data
-RUN mkdir -p /var/www/${PROJECT}/storage
-RUN chown -R www-data:www-data /var/www/${PROJECT}/storage
+RUN mkdir -p /var/www/${PROJECT}/storage && \
+    chown -R www-data:www-data /var/www/${PROJECT}/storage
 
 EXPOSE 9000
 
 ENTRYPOINT ["./entrypoint.sh"]
 
-CMD ["php-fpm"]
-
+CMD ["php-fpm"]