VM Architecture Docs

docs/admin/planning/vm-cluster.md

@@ -4,5 +4,38 @@ tags:
   - planning
 ---
 
-This is a placeholder
+What if you need four or five nines availability, but cloud native is not
+an option? You could cluster Janssen using VM's, but you'll have to do
+some legwork, because we don't publish tools for this task. This planning
+guide will cover some of the things you'll need to consider.
 
+1. **Hostname**
+
+Remember when you run the linux setup to use the hostname of the cluster,
+not the hostname of the individual server.  This is important because the
+OpenID Provider metadata needs to use the public hostname (i.e. the URL's
+you'll find at `/.well-known/openid-configuration`)
+
+1. **Load Balancing / SSL** As Auth Server and FIDO (the two Internet facing
+components) are stateless,  you can use any load balancer routing algorithm,
+even round robin. You can also use the load balancer to terminate SSL.
+
+1. **Database** The web services Janssen Components share the database, so
+you'll have to use database replication (e.g. OpenDJ replication). You could
+also use a cloud database that takes care of replication for you.
+
+1. **Cache** You can't use `IN-MEMORY` cache which would have no way to
+replicate to the other nodes in the network. You could use the Database
+for caching, although this will impact performance, although it's only an
+issue for high concurrency use cases. Our recommendation is to use Redis for
+caching, which has less cache hit misses then Memcached.
+
+1. **Key management** Where to you store the private keys? If on the file
+system, you'll have to make sure that they get securely copied. This is
+trickier then it sounds because of key rotation. OpenID Connect working group
+suggests key rotation every two day, to make sure developers who write OpenID
+applications handle key rotation properly in their code, and don't hardcode
+the metadata, but retrieve it from the OpenID configuration endpoint.
+
+1. **Customizations** You must copy any libraries, xhtml pages, CSS or
+javascript must be available on all servers. 

docs/admin/planning/vm-single-instance.md

@@ -4,5 +4,29 @@ tags:
   - planning
 ---
 
-This is a placeholder
+While an active-active cluster enables you to achieve four or five nines
+uptime, you may want to consider a single VM instance if simplicity of
+operation trumps availability. If you do a good job at monitoring, and
+can restore from backup quickly, it's certainly possible to meet an SLA
+of 99.9% availability using just one server.
 
+Janssen has linux packages available for SUSE, Red Hat and Ubuntu. One
+operational consideration is that you should `hold` the version
+of Jans Auth Server, to avoid update during the normal package update process.
+As many applications may rely on a central IDP, you want to plan updates and
+have a rollback plan if something goes wrong. An automated, unattended update
+process for the IDP is too risky.
+
+An important security tradeoffs when you run Janssen on a single VM is that
+services which you want to control access to are running on a server with
+an Internet-facing ethernet interface: the Config API, database, and SCIM
+server. Even though these service are running on `localhost`, if the Internet
+facing interface was compromised, network protection could be bypassed.
+
+The main advantage of running a single VM is simplicity. Your sys admins won't
+need any special training. And it will be easy to install, backup,
+monitor, and configure your deployment. If you have many autonomous domains,
+each with their own brand and user identity management process, the simplicity
+of running a single IDP might be the best solution. If three nines is acceptable
+to your business, the expense of deploying and operating a cluster may not be 
+justified.