Name: django-gulp-nginx
Owner: Ansible
Description: Django + PostgreSQL + Nginx with Gulp-built static assets framework, managed with Ansible Container
Created: 2016-12-12 16:08:27.0
Updated: 2018-01-04 23:35:48.0
Pushed: 2017-06-20 15:30:38.0
Size: 120
Language: Python
GitHub Committers
User | Most Recent Commit | # Commits |
---|
Other Committers
User | Most Recent Commit | # Commits |
---|
A framework for building containerized django applications. Utilizes Ansible Container to manage each phase of the application lifecycle, and enables you to begin developing immediately with containers.
Includes django, gulp, nginx, and postgresql services, pre-configured to work together, and ready for development. You can easily adjust the settings of each, as well as drop in new services directly from Ansible Galaxy. The following topics will help you get started:
Before starting, you'll need to have the following:
To start creating your Django application, create a new directory, and initialize it with a copy of this project:
eate a new directory for your project
dir demo
t the working directory
demo
itialize the project
sible-container init ansible.django-gulp-nginx
Next, build a local copy of the project's images. From the new project directory, start the build process by running the following:
eate the container images
sible-container build
The build process will take a few minutes to complete. It will take longer the first time you run it, because it needs to pull the base image, and build the Conductor image.
After the Conductor build completes, each service in the container.yml file will be built. Services are built by executing one or more Ansible roles, and as the build process progresses, task names will scroll across your session window as each role executes.
Once completed, you'll have a local copy of the built images that can be used to run the application. When you're ready to start the application, run the following:
art the containers
sible-container run
Requests are proxied through the gulp service. Before you can view the sample web page, the gulp web server needs to be started. This may take a couple moments, as the process first install node modules and bower components prior to starting the service. You can watch the logs by running the following:
tch the logs for gulp service
cker logs -f demo_gulp_1
The following message in the logs indicates the service is running:
05:29] Starting 'js'...
Access URLs:
--------------------------------
Local: http://localhost:8080
External: http://172.21.0.4:8080
--------------------------------
UI: http://localhost:3001
External: http://172.21.0.4:3001
--------------------------------
Serving files from: dist
05:30] Finished 'lib' after 601 ms
05:30] Finished 'html' after 574 ms
05:30] Finished 'sass' after 644 ms
05:30] Finished 'templates' after 685 ms
05:30] Finished 'js' after 631 ms
To view the sample app, open a browser and go to http://localhost:8080, where you'll see a simple “Hello World!” message.
When you start the containers with ansible-container run
, they start in development mode, which means that the dev_overrides section of each service definition in container.yml takes precedence, causing the gulp, django and postgresql services to start, and the nginx service to stop.
The frontend code can be found in the src directory, and the backend django code is found in the project directory. You can begin making changes right away, and as you do, you'll see the results reflected in your browser almost immediately.
Here's a brief overview of each of the running services:
While developing, the gulp service will actively watch for changes to files in the src directory tree, where custom frontend components (i.e. html, javascript, css, etc.) live. As new files are created, or existing files modified, the gulp service will compile the updates, place results in the dist directory, and using browsersync, refresh your browser.
In addition to compiling the frontend components, the gulp service will proxy requests beginning with /static or /admin to the django service. The proxy settings are configurable in gulpfile.js, so as you add additional routes to the django service, you can expand the number of paths forwarded by the gulp service.
NOTE
As you add new routes to the backend, be sure to update the nginx service definition by modifying container.yml, and adjusting the parameters passed to the ansible.nginx-container role. Specifically, you'll need to update the PROXY_LOCATION value.
The django service provides the backend of the application. During development the runserver process executes, and accepts requests from the gulp service. The source code to the Django app lives in the project directory tree. To add additional Python and Django modules, add the module names and versions to requirements.txt, and run the ansible-container build
command to install and incorporate them into the django image.
When the django container starts, it waits for the PostgreSQL database to be ready, and then it performs migrations, all before starting the server process. Use make django_manage makemigrations
and make django_manage migrate
to create and run migrations during development.
The postgresql service provides the django service with access to a database, and by default stores the database on the postgres-data volume. Modify container.ym to set the database name, and credentials.
You can add preconfigured services to the application by installing Container Enabled roles directly from the Galaxy web site. Look for roles on the site by going to the Browse Roles page, setting the filter to Role Type, and choosing Containr Enabled.
For example, if you want to install a Redis service, you can install the j00bar.redis-container
role by running the following:
t the working directory to your project root
demo
stall the role
sible-container install j00bar.redis-container
After the install completes, the new service will be included in container.yml. You'll then need to run the build
process to update the project's images:
build the project images
sible-container build
After the build process completes, restart the application by running the following:
n the application
sible-container restart
After you've made changes to the app, and you're ready to test, you'll first run ansible-container build
to create a new set of images containing the latest code. During the build process, the project directory, which contains your custom Django files, will be copied into the django image at /django, and your frontend assets, contained in src, will be compiled and copied to the dist directory, and then copied into the nginx image at /static.
Once the new images are built, run the following to test the images:
start the application in production mode for testing
sible-container stop
sible-container run --production
The above starts the containers in production mode, ignoring the dev_overrides section of each service definition in container.yml`, and executing the containers as if they were deployed to production. This time the django, nginx, and postgresql containers starts, and the gulp container stops. Just as before, access the application at http://localhost:8080.
In production this service will run the gunicorn process to accept requests from the nginx service. Just as before, when the service starts it will wait for the PostgreSQL database to become available, and then perform migrations, before starting the server process.
This service will respond to requests for frontend assets, and proxy requests to django service endpoints. Before running ansible-container build
, if you added new routes to your django application, be sure to update the nginx configuration by modifying container.yml, and adjusting the PROXY_LOCATION parameter passed to the ansible.nginx-container role. This will impact the nginx.conf file that gets added to the image.
Just as before, the postgresql sevice provides the django service with access to a database, and by default stores the database on the postgres-data volume.
NOTE
If you start the image build process by running
make build
, the postgres-data volume will be deleted, and the application will start with an empty database.
Ansible Container can deploy to Kubernetes and OpenShift. For the purposes of demonstrating the deployment workflow, we'll use OpenShift. If you want to carry out the actual steps, you'll need access to an OpenShift instance. The Install and Configure Openshift guide at our doc site provides a how-to that will help you create a containerized instance.
Log into the cluster using your developer account:
g into the local cluster
login -u developer
Create a demo project:
eate a new project
new-project demo
The project name is defined in container.yml. Within the settings section, you will find a k8s_namespace section that sets the name. The project name is arbitrary. However, before running the deploy
command, the project must already exist, and the user you're logged in as, must have access to it.
Next, use the deploy
command to push the project images to the local registry, and create the deployment playbook. For demonstration purposes, we're referencing the local_openshift registry defined in container.yml. Depending on how you created the local OpenShift cluster, you may need to adjust the registry attributes.
One of the registry attributes is namespace. For OpenShift and K8s, the registry namespace should match the name value set in k8s_namespace within the settings section. In the case of OpenShift, the name in k8s_namespace will be the project name, and for K8s, it's the Namespace.
Once you're ready to push the images, run the following from the root of the demo project directory:
sh the built images and generate the deployment playbook
sible-container --engine openshift deploy --push-to local_openshift --username developer --password $(oc whoami -t)
The above will authenticate to the registry using the developer
username, and a token generated by the oc whoami -t
command. This presumes that your cluster has a developer
account, and that you previously authenticated to the cluster with this account.
After pushing the images, a playbook is generated and written to the ansible-deployment
directory. The name of the playbook will match the project name, and have a .yml
extension. In this case, the name of the playbook will be demo.yml
.
You will also find a roles
directory containing the ansible.kubernetes-modules
role. The deployment playbook relies on this role for access to the Ansible Kubernetes modules.
To deploy the application, execute the playbook, making sure to include the appropriate tag. Possible tags include: start
, stop
, restart
, and destroy
. To start the application, run the following:
n the deployment playbook
sible-playbook ./ansible-deployment/demo.yml --tags start
Once the playbook completes, log into the OpenShift console to check the status of the deployment. From the Applications menu, choose Routes, and find the URL that points to the nginx service. Using this URL, you can access the appication running on the cluster.
If you work with this project and find issues, please submit an issue.
Pull requests are welcome. If you want to help add features and maintain the project, please feel free to jump in, and we'll review your request quickly, and help you get it merged.
This project depends on the following Galaxy roles:
View AUTHORS for a list contributors. Thanks everyone!