A site's "realm" or "software realm" refers to the combined collection of all the operating system files, programming languages, and third-party applications present in its environment. These are the tools available to your site for web applications, and for use over ssh.
Some people want the latest and greatest versions of applications, particularly programming languages, especially while they are developing a new site. Others strongly prefer things stay as stable as possible so they don't have to deal with their site breaking every time a non-backward-compatible change gets made by some application developer, especially once their site is up and working.
Likewise, security updates always run the risk of breaking things. Some people prefer to receive security updates immediately to minimize the risk of exposure. Other people prefer to defer updates to a time of their choosing, so they can deal with any problems that result, to minimize the risk of downtime.
Because these desires conflict, we provide multiple types of site realms. They are broadly divided into the following types:
- Stable/Current
- This is the default realm assigned to new sites. It receives only security updates and important (i.e. "stuff is broken") fixes. If you don't know which realm to choose, choose the Stable/Current realm.
- Stable/Upcoming
- This is a newer stable realm that will become the default for new sites in the future. It receives only security updates, important (i.e. "stuff is broken") fixes, and (rarely) some non-disruptive new package requests. If you want to get your stuff working in a stable environment that will receive fixes for as long as possible, choose this.
- Beta
- This is a realm that receives frequent updates (as often as weekly). Although it won't become stable, it serves as a blueprint for future stable realms. New packages will be installed into a beta realm first. Beta realms also receive frequent updates, including security fixes, bug fixes, and upgrades to installed packages. Programming languages and other software may receive frequent upgrades, some of which may impair backwards compatibility, without advanced notice.
- Experimental
- This is a realm that is not designed to become stable. It contains bleeding-edge languages or software that are grossly incompatible with other realms. Experimental realms may receive large, potentially incompatible, updates at any time. Experimental realms are not supported or recommended for any production usage.
- Stable/Deprecated
- This is an older stable realm that is still supported but will be obsolete soon. Once a realm becomes obsolete, any sites still using it will be automatically moved to the current Stable/Upcoming realm. Deprecated realms receive no updates.
We add new stable realms based on the then-current beta realm about every three months. These new realms are stable and reliable but remain "Upcoming" for about three months to shake out any weird defects or bugs before becoming the current stable realm. Newly-created sites will start in the current stable realm and, by default, when a new realm becomes current, sites in older realms will be automatically migrated to it.
A site's schedule for automatic realm upgrades can be adjusted via the "Realm Updates" setting in the "Config Information" box on the Site Information Panel. This gives you some control over when to upgrade. If you select the "late" update option, we recommend that you upgrade your site's realm manually about every six months to avoid falling too far behind. (The farther behind you fall, the greater the likelihood of problems when you update.) Although rare, compatibility issues are possible, so it's best to do this at a time when you are ready to deal with them.
You can also switch between available site realms, or get a list of currently-supported realms, by selecting "Edit" on the "Software Realm" line of the same box.
Caution: This is not a subtle change; if you're logged in to ssh when you change realms, it will attempt to kick you off. It is a little like rebooting. So make sure you have saved your work!