From 896707f7d54180965f45c2789919e397f824acdb Mon Sep 17 00:00:00 2001 From: Alvin Bryan <107407814+alvinometric@users.noreply.github.com> Date: Wed, 4 Sep 2024 09:14:55 +0100 Subject: [PATCH] Django tutorial + Nav update (#7982) Updating the nav so Django and Rails are both listed under their respective language. --------- Co-authored-by: Simon Hornby Co-authored-by: Melinda Fekete --- .../{python => django}/django-examples.md | 2 +- .../implementing-feature-flags-django.md | 170 ++++++++++++++++++ .../rails/implementing-feature-flags-rails.md | 12 +- website/sidebars.js | 28 +-- 4 files changed, 191 insertions(+), 21 deletions(-) rename website/docs/feature-flag-tutorials/{python => django}/django-examples.md (99%) create mode 100644 website/docs/feature-flag-tutorials/django/implementing-feature-flags-django.md diff --git a/website/docs/feature-flag-tutorials/python/django-examples.md b/website/docs/feature-flag-tutorials/django/django-examples.md similarity index 99% rename from website/docs/feature-flag-tutorials/python/django-examples.md rename to website/docs/feature-flag-tutorials/django/django-examples.md index 0c71d1cc07..34debb792b 100644 --- a/website/docs/feature-flag-tutorials/python/django-examples.md +++ b/website/docs/feature-flag-tutorials/django/django-examples.md @@ -3,7 +3,7 @@ title: Django Feature Flag Examples slug: /feature-flag-tutorials/django/examples --- -In our [Python feature flag tutorial](/feature-flag-tutorials/python), we implemented a simple feature flag that could be turned on and off. In the real world, many feature flag use cases have more nuance than this. This document will walk you through some common examples of using feature flags in Django with some of those more advanced use cases in mind. +In our [Django feature flag tutorial](/feature-flag-tutorials/django), we implemented a simple feature flag that could be turned on and off. In the real world, many feature flag use cases have more nuance than this. This document will walk you through some common examples of using feature flags in Django with some of those more advanced use cases in mind. We built multiple features into Unleash, an open-source feature flag platform, to address the complexities of releasing code and managing feature flags along the way. This tutorial will explore the following: diff --git a/website/docs/feature-flag-tutorials/django/implementing-feature-flags-django.md b/website/docs/feature-flag-tutorials/django/implementing-feature-flags-django.md new file mode 100644 index 0000000000..6825b5fe42 --- /dev/null +++ b/website/docs/feature-flag-tutorials/django/implementing-feature-flags-django.md @@ -0,0 +1,170 @@ +--- +title: How to Implement Feature Flags in Django +description: "How to use Unleash feature flags with Django." +slug: /feature-flag-tutorials/django +--- + +Hello! In this tutorial, we’ll show you how to add feature flags to your Django app, using [Unleash](https://www.getunleash.io/) and the official [Unleash Python SDK](https://docs.getunleash.io/reference/sdks/python). With Unleash, an open-source feature flag service, you can use our tooling to add feature flags to your application and release new features faster. + +In a classic tutorial fashion, we’ll add feature flags to a blog app made with Django. We’ll use feature flags to decide how many blog posts to show on the index page. + +## Prerequisites + +For this tutorial, you'll need the following: + +- Python3.10+ +- Git +- Docker and Docker Compose + +![architecture diagram for our implementation](../rails/diagram.png) + +The Unleash Server is a **Feature Flag Control Service**, which manages your feature flags and lets you retrieve flag data. Unleash has a UI for creating and managing projects and feature flags. For server-side applications or automated scripts, Unleash exposes an [API](/reference/api/unleash) defined by an OpenAPI specification, allowing you to perform these actions programmatically. + +## 1. Install a local feature flag provider + +In this section, we'll install Unleash, run the instance locally, log in, and create a feature flag. If you prefer, you can use other tools instead of Unleash, but you'll need to update the code accordingly. The basic steps will probably be the same. + +Use Git to clone the Unleash repository and Docker to build and run it. Open a terminal window and run the following commands: + +``` +git clone https://github.com/unleash/unleash.git +cd unleash +docker compose up -d +``` + +You will now have Unleash installed onto your machine and running in the background. You can access this instance in your web browser at [http://localhost:4242](http://localhost:4242). + +Log in to the platform using these credentials: + +``` +Username: admin +Password: unleash4all +``` + +Click the 'New feature flag' button to create a new feature flag. + +![Create a new feature flag](../ruby/new-ff.png) + +Call it `top-3` and enable it in the `development` environment. + +![A feature flag called `top-3` is now visible.](../rails/enable-ff.png) + +Everything's now set up on the Unleash side. Let's set up the Django application. + +## 2. Set up the Django app + +Let's clone a basic blog repository and get it up and running. We don't want to waste time setting up a Django codebase from scratch. + +```sh +git clone https://github.com/alvinometric/django-basic-blog +cd django-basic-blog +``` + +After that, set up a virtual environment and install Django. + +```sh +python3 -m venv venv +source venv/bin/activate +pip install django +``` + +#### Set up and seed the database + +This repository uses SQLite, so no additional dependencies or migrations are required. + +```sh +python manage.py loaddata initial_data.json +``` + +#### Run the server + +```sh +python manage.py runserver +``` + +Go to [http://localhost:8000](http://localhost:8000) and check that you see the following: + +![A blog app with a list of posts](../rails/blog-app.png) + +## 3. Restrict the number of posts + +Right now all the blog posts are displayed on the index page. We want to use a feature flag to change that and restrict it to the 3 most recent posts. + +Let's create a static boolean flag, for now. + +Modify the `post_list` view in `blog/views.py` to look like this: + +```python +from django.shortcuts import render +from .models import Post + +def post_list(request): + is_top3 = True + posts = Post.objects.order_by('-published_date')[:3] if is_top3 else Post.objects.all() + return render(request, 'blog/post_list.html', {'posts': posts}) +``` + +We're using the flag in the views rather than the template, but you could also do it there. I prefer keeping my template logic as simple as possible. + +Reload your browser and you should see only the 3 most recent posts. + +## 4. Add Unleash to your Django app + +Now, let's connect our project to Unleash so that you can toggle the feature flag at runtime. If you wanted to, you could also do a gradual rollout, and use it for A/B testing or more advanced functionality. + +You'll need 2 things: + +- The URL of your Unleash instance's API. It's `http://localhost:4242/api/` for your local version. You'll want to replace it with your remote instance. +- The API token we created on our Unleash instance. + +First, install the `UnleashClient` package: + +```sh +pip install UnleashClient +``` + +Then, create `blog/unleash_client.py`, and add the following: + +```python +# You DO NOT want to do this in a production environment +# Rather, you would create a singleton that is shared across your application +from UnleashClient import UnleashClient + +unleash_client = UnleashClient( + url="http://localhost:4242/api/", + app_name="django-blog", + custom_headers={'Authorization': ''} +) +unleash_client.initialize_client() +``` + +Then, in `blog/views.py`, update the `post_list` view: + +```python +from django.shortcuts import render +from .models import Post +from .unleash_client import unleash_client + +def post_list(request): + if unleash_client.is_enabled("top-3"): + posts = Post.objects.order_by('-published_date')[:3] + else: + posts = Post.objects.order_by('-published_date') + return render(request, 'blog/post_list.html', {'posts': posts}) +``` + +## 6. Verify the toggle experience + +Reload your browser and check that you see three blog posts displayed. Turn off the flag in your Unleash instance and reload the page. You should see all the blog posts again. + +See additional use cases in our [Python SDK documentation](https://docs.getunleash.io/reference/sdks/python). + +## Conclusion + +All done! Now you know how to add feature flags with Unleash in Django. You've learned how to: + +- Install Unleash +- Create and enable a feature flag +- Grab the value of a feature flag with the Python SDK, and use it in a Django app + +Thank you for following this tutorial! diff --git a/website/docs/feature-flag-tutorials/rails/implementing-feature-flags-rails.md b/website/docs/feature-flag-tutorials/rails/implementing-feature-flags-rails.md index a373f9bfea..9b983f0dd8 100644 --- a/website/docs/feature-flag-tutorials/rails/implementing-feature-flags-rails.md +++ b/website/docs/feature-flag-tutorials/rails/implementing-feature-flags-rails.md @@ -4,7 +4,7 @@ description: "How to use Unleash feature flags with Rails." slug: /feature-flag-tutorials/rails --- -Hello! In this tutorial, we’ll show you how to add feature flags to your Ruby on Rails app, using [Unleash](https://www.getunleash.io/) and the official [Unleash Ruby SDK](https://docs.getunleash.io/reference/sdks/ruby). With Unleash, an open-source feature flag service, you can use our tooling to add feature flags to your application and release new features faster. +Hello! In this tutorial, we’ll show you how to add feature flags to your Ruby on Rails app, using [Unleash](https://www.getunleash.io/) and the official [Unleash Ruby SDK](/reference/sdks/ruby). With Unleash, an open-source feature flag service, you can use our tooling to add feature flags to your application and release new features faster. In a classic tutorial fashion, we’ll add feature flags to a blog app made with Ruby on Rails. We’ll use feature flags to decide how many blog posts to show on the index page. @@ -30,7 +30,7 @@ For this tutorial, you’ll need the following: ![architecture diagram for our implementation](./diagram.png) -The Unleash Server is a **Feature Flag Control Service**, which manages your feature flags and lets you retrieve flag data. Unleash has a UI for creating and managing projects and feature flags. There are also [API commands available](https://docs.getunleash.io/reference/api/unleash) to perform the same actions straight from your CLI or server-side app. +The Unleash Server is a **Feature Flag Control Service**, which manages your feature flags and lets you retrieve flag data. Unleash has a UI for creating and managing projects and feature flags. There are also [API commands available](/reference/api/unleash) to perform the same actions straight from your CLI or server-side app. ## 1. Best practices for back-end apps with Unleash @@ -41,7 +41,7 @@ Most importantly, you must: - Limit feature flag payloads for scalability, security, and efficiency - Use graceful degradation where possible to improve the resiliency of your architecture -For a complete list of architectural guidelines, including caching strategies, see our [best practices for building and scaling feature flag systems](https://docs.getunleash.io/topics/feature-flags/feature-flag-best-practices). +For a complete list of architectural guidelines, including caching strategies, see our [best practices for building and scaling feature flag systems](/topics/feature-flags/feature-flag-best-practices). ## 2. Install a local feature flag provider @@ -147,7 +147,7 @@ You’ll need 2 things: First, install the `unleash` gem. ```sh -gem install unleash +bundle add unleash ``` Then, create `config/initializers/unleash.rb`, and add the following: @@ -165,7 +165,7 @@ UNLEASH = Unleash::Client.new ``` -You can check our [API tokens and client keys documentation](https://docs.getunleash.io/reference/api-tokens-and-client-keys) for more information. +You can check our [API tokens and client keys documentation](/reference/api-tokens-and-client-keys) for more information. Then, in `app/controllers/application_controller.rb`, add the following method: @@ -197,7 +197,7 @@ class PostsController < ApplicationController Reload your browser and check that you see three blog posts displayed. Turn off the flag in your Unleash instance and reload the page. You should see all the blog posts again. -See additional use cases in our [Server-Side SDK with Ruby](https://docs.getunleash.io/reference/sdks/ruby) documentation. +See additional use cases in our [Server-Side SDK with Ruby](/reference/sdks/ruby) documentation. > **Note:** An update to a feature flag may take 30 seconds to propagate. diff --git a/website/sidebars.js b/website/sidebars.js index 5f7ae8a234..4bb4a18d5e 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -127,8 +127,13 @@ module.exports = { }, { type: 'doc', - label: 'Django', - id: 'feature-flag-tutorials/python/django-examples', + label: 'Django Tutorial', + id: 'feature-flag-tutorials/django/implementing-feature-flags-django', + }, + { + type: 'doc', + label: 'Django Examples', + id: 'feature-flag-tutorials/django/django-examples', }, ], }, @@ -162,22 +167,17 @@ module.exports = { items: [ { type: 'doc', - label: 'Examples', + label: 'Ruby Examples', id: 'feature-flag-tutorials/ruby/ruby-examples', }, - ], - }, - { - type: 'category', - label: 'Ruby on Rails', - link: { - type: 'doc', - id: 'feature-flag-tutorials/rails/implementing-feature-flags-rails', - }, - items: [ { type: 'doc', - label: 'Examples', + label: 'Rails Tutorial', + id: 'feature-flag-tutorials/rails/implementing-feature-flags-rails', + }, + { + type: 'doc', + label: 'Rails Examples', id: 'feature-flag-tutorials/rails/rails-examples', }, ],