Environments

Typically when a website is being created, it will go through 3 different "environments". The development environment - literally on a developers computer - to a staging environment where the project owner can review changes, then finally on in to production. These 3 are commonly called dev, stage and prod in short form. Socialstack has some convenience mechanisms to allow configuration and code to target specific environments, with the caveat of some important best practises around this.

Code varying by environment

This is best avoided for a reason which will be touched on shortly. If your code must vary by environment, you can use the Environment class in the Api.Configuration namespace:

using Api.Configuration;


Environment.IsProduction(); // true/ false

Environment.IsStaging(); // true/ false

Environment.IsDevelopment(); // true/ false. This is almost never used and is instead more common to see #if DEBUG.

Best practises

Code which checks if it is running on stage or production has a nasty caveat: It probably isn't going to be tested until it actually goes live. This can result in failed deployments and major downtime. If you do use environment specific code, make sure all code routes are at least tested beforehand. Instead though, favour environment specific configuration which is also easier to test before it goes live, as you can test it via quick configuration edits in the administration panel before it goes live too.

How a server knows which environment it is

A project's appsettings.json must always define an Environment field. Typically the value in here is one of "dev", "stage" or "prod". Deployed environments extend and override appsettings fields primarily with an appsettings.extension.json file.

For example, a site deployed on SocialStack cloud will have its project appsettings.json as-is and then an appsettings.extension.json which declares Environment:stage or Environment:prod, which overrides whatever was in the original appsettings.json file. This extension file is also how environment specific database and metrics tracking configuration is passed in.

Environment specific configuration

Based on the best practises above, you'll generally want to use environment specific configuration rather than code which varies based on the environment it detects. To do this, create multiple configuration entries in the configuration part of the admin panel with the same key. Configuration has a field called "Environments" which contains a comma separated list of the environments that this configuration entry applies to. Just like the Environment field, it is usually the environment shorthand name in lowercase.

When a server loads configuration, it checks the environment field to see if it contains the environment name that this server is running as. This is a loose test meaning "production" will match "prod" and "staging" will match "stage" but it's generally recommended to stick with the lowercase shorthand (dev, stage, prod) just in case custom code is explicitly checking this field for some unseen use cases.

For example, a configuration entry with "Environments" set to "dev,stage" will be ignored by a production server. You should then have a separate configuration entry with the same key with "Environments" set to "prod" to configure production instances as well. This has the advantage of all servers being able to use the same configuration table making database dumps straight forward and more portable.