Installation of FeatureHub
There are several deployment options for running FeatureHub. As FeatureHub is packaged as a Cloud Native bundle, all parts are Docker images and are intended to be used with that technology (i.e. Docker/OCI or Kubernetes).
There is a GitHub repository where you can find sample docker-compose style deployment options.
All the deployment options mount the database volume separately from the main set of containers, allowing you to upgrade your database and versions of FeatureHub without destroying your database.
| As FeatureHub is an open source project, we develop on only a limited number of databases, primarily Postgres. |
We provide and maintain database migrations scripts for Postgres, MySQL, MariaDB, and Oracle.
There is also a MariaDB and Oracle example docker-compose install, and the MariaDB and MySQL drivers are installed in all server runtimes. Further we include support for Google’s Cloud SQL libraries in the base images if you need to use their secure tunnelling capability.
Other databases can potentially be added, please feel free to lodge a ticket on our Github Issues register, particularly if you are willing to test it out.
Deployment Options
As explained in the Architecture section, there are a number of different combinations for deployment of FeatureHub. Those typically focus on where you will deploy the infrastructure, how you want your clients to use it and how much use it will get. FeatureHub as of 1.5.0 is designed to support very low use cases of only hundreds of requests a day up to tens of millions of requests a day or more.
To get you up and going quickly, we have created a number of different Docker options using Docker-Compose.
You can check for the latest versions here
To install, clone the featurehub-install repo or download using the command below:
curl -sL https://github.com/featurehub-io/featurehub-install/tarball/main | tar -xvz
Make sure you have your docker server running and docker-compose installed if you are using it (or your swarm set up if you are using docker stack). These example stacks are great for experimenting or to understand what the different capabilities of the FeatureHub stack are - for example read replica databases, OAuth2 configuration for your provider, multiple NATs servers and so forth.
Evaluation Deployment
For the Evaluation option (not recommended for production):
cd docker-compose-options/all-in-one-h2
docker compose up
This will install all the necessary components including FeatureHub Admin Console. You can now load it on http://localhost:8085
What makes it only an evaluation option is simply the database used (H2), it writes to the local disk and is not intended to be used for a long-running or highly performant, concurrent system.
Production-Ready Deployments
| Streaming | App traffic volume | Option | Recommendation |
|---|---|---|---|
Yes |
Low |
1a |
Suits a simple container deployment platform like ECS, Compute Engine with a single Docker instance and using Party Server |
Yes |
Mid-High |
2a |
Suits a Kubernetes deployment like GKS,EKS,AKS or a more complex ECS based deploy and using Edge/Dacha deployed separately from Admin App |
No |
Low |
1b |
Suits a Party-Server-ish deployment with a single database on Cloud Run or Azure Container Instances. Could also deploy to platform like ECS or Compute Engine but less cost-effective. |
No |
Mid |
2b |
Suits a MR deployment with a single master and one or more read replicas, with Edge-Rest pointed at the read replicas. |
Option 1a - Low Volume Deployment (Streaming)
With Option 1a (the Party Server) all the services are deployed in a single running container. Internally this is packaged as a single Java server running four different services (a static web server serving the Admin App, the Management Repository server, the cache and the Edge service), and also the NATs service bus to provide cache and streaming services. This allows you to run only one of these (for instance) and support a full streaming service talking to an external database.
The image is the same as the basic evaluation image with the difference being the database (we recommend Postgres).
Because the single container is responsible for handling all incoming requests (including requests for features), this will mean it should be able to handle around 150-200 concurrent requests per CPU, but streaming requests will further limit that capacity. As such, it causes Edge traffic to compete with Admin traffic.
You can run up multiple Party Servers, in this case the nats.urls configuration (see below) must
be set correctly for discovery (along with allowing network traffic between them). If you start doing this, it is likely a better
choice to split them into multiple parts - with Admin on one server and Edge/Dacha on others. If you think your usage will grow, we
encourage you to use different DNS hosts pointing to the same server for features vs the Admin app.
Setup Instructions
For Postgres option:
cd docker-compose-options/all-in-one-postgres
docker compose up
Or for MySQL option:
cd docker-compose-options/all-in-one-mysql
docker compose up
This will install all the necessary components including FeatureHub Admin Console. You can now load it on localhost:8085
Option 1b - Low Volume Deployment (Non-streaming)
In this case, this deployment, known as party-server-ish is different from the evaluation image, and deploys only the Management
Repository and a version of Edge that talks to the database. The party-server-ish serves the website, Admin App and Edge-Rest applications
running inside a single process. There is no NATS or Dacha, and no SSE based
streaming capability available.
This kind of option is suitable if you are only using GET requests (being able to use the test API to update features remains available), such as for mobile or Web applications.
As with all deploys, you can configure a read replica for each container, and Edge requests will hit the replica by default (as they are read only).
Option 2a - Streaming Scalable Deployment
This option is best if you want to run FeatureHub in production at scale. Running separate instances of Edge, Cache, NATS and FeatureHub MR Server, means you can deploy these components independently for scalability and redundancy, and Docker images are provided for each of these services (see our docker-compose section below).
Because they are deployed in separate containers, you have considerably greater control over what network traffic gains access to each of these pieces, and they do not all sit under the same Web server. This kind of deployment is intended for situations where you want streaming support, or where you want much greater volume or response than the 2b solution can provide you. The Dacha servers are able to support massive horizontal scaling of features and feature updates, further scaling up and not creating a load on the database as necessary by the use of the NATS cluster.
We provide an installation option with Postgres database. It brings up the Admin App (MR), the cache (Dacha), the Edge server, the distributed bus (NATS) and the database all as separate services. Edge runs on a different port to the Admin App and shows how you can use a different URL to serve traffic for feature consumers from your Admin App.
Setup Instructions
cd docker-compose-options/all-separate-postgres
docker compose up
There is also a helm chart available for production Kubernetes deployment for this option. Please follow documentation here. It doesn’t include a Postgres or NATs server as generally your cloud provider will have a managed Postgres service, and NATs have their own Kubernetes Helm charts for scalable, reliable deploys.
Option 2b - Non-Streaming Scalable Deployment
This option is limited only by the number of read replicas you can support and the method you have over balancing access
to these replicas. This deployment uses the separation of mr (the Admin App and its backend) from edge-rest instead of bundling
them together and configuring a read replica for edge-rest (the only time we recommend doing this). As many cloud providers
allow you to configure multiple active read replicas, potentially across different zones of the world, this allows you to scale
your connectivity across those replicas. See the documentation below on Database Read Replicas for how to configure this.
Cloud Deployments
Deploying FeatureHub (non-streaming) on Google Cloud Run
Google Cloud Run lets you spin up a container instance and multiplex requests to it, making it directly available as soon as you have configured it. These are basic instructions on how to do this.
Create your Cloud SQL Instance
In this example we use the instance of Postgres 13 of the smallest possible size and deploy a 2 cpu, 512Mb Cloud Run instance that scales from 0 to 3, allowing up to 400 incoming requests concurrently per instance. Each CPU for incoming Edge requests is capable of supporting around 200 concurrent requests. The CPU of the database affects the speed at which the instances respond - for example we were only able to sustain around 50 requests per second (with around a 650ms time per request) with a 0.6 CPU database.
export GCP_REGION=us-east1 export GCP_ZONE=us-east1-b gcloud config set project your-project gcloud config set compute/zone $GCP_ZONE
We are now going to create a Cloud SQL database, so you need to choose a root password, a database name and a schema name. We will create a very small instance that is zonal only, has no daily backup, and connectivity via public IP but SSL - Cloud SQL pricing give you more details on how much this will cost. Obviously you can choose a larger one, but this initial deployment will probably be throwaway as it is quite easy. This step takes a while
export FH_DB_NAME=featurehub-db export FH_DB_PASSWORD=FeatureHub17# export FH_DB_SCHEMA=featurehub gcloud sql instances create $FH_DB_NAME --database-version=POSTGRES_13 --zone=$GCP_ZONE --tier=db-f1-micro "--root-password=$FH_DB_PASSWORD" --assign-ip --require-ssl --storage-type=SSD
this should just show you a database schema called postgres
gcloud sql databases list --instance=$FH_DB_NAME
Now create the new featurehub database schema
gcloud sql databases create $FH_DB_SCHEMA --instance $FH_DB_NAME
now get the "connection name" - it is the connectionName parameter from this:
gcloud sql instances describe $FH_DB_NAME
You need it in the custom properties below. In my case this was
backendType: SECOND_GEN connectionName: featurehub-example:us-central1:featurehub-db databaseVersion: POSTGRES_13 ...
this becomes the name you pass to the container
export FH_DB_CONN_NAME=featurehub-example:us-central1:featurehub-db
Create your Cloud Run deployment
export FH_CR_NAME=featurehub export FH_IMAGE=featurehub/party-server-ish:1.5.4
Note that you need to be a Project Owner or Cloud Run Admin to allow unauthenticated traffic.
export HOST_URL=http://localhost gcloud run deploy $FH_CR_NAME --image=$FH_IMAGE --min-instances=0 --max-instances=3 --cpu=2 --memory=512Mi --port=8085 --concurrency=400 "--set-env-vars=db.url=jdbc:postgresql:///$FH_DB_SCHEMA,db.username=postgres,db.password=$FH_DB_PASSWORD,db.minConnections=3,db.maxConnections=100,monitor.port=8701,db.customProperties=cloudSqlInstance=$FH_DB_CONN_NAME;socketFactory=com.google.cloud.sql.postgres.SocketFactory" --set-cloudsql-instances=$FH_DB_NAME --platform=managed --region=$GCP_REGION --allow-unauthenticated
If you are using OAuth2, then you will need to set those properties, and we recommend setting your oauth2.disable-login to true to
prevent being able to log in without an OAuth2 connection.
Use the example Cloud Shell to ensure you can connect to it, but it can take a while to create.