Environments - Revision history

Luke: /* Code varying by environment */

2023-04-25T17:27:52Z

Code varying by environment

← Older revision		Revision as of 17:27, 25 April 2023
Line 24:		Line 24:


	<html data-env-dev ..		<html data-env="dev" ..
	<html data-env-stage ..		<html data-env="stage" ..
	<html data-env-prod ..		<html data-env="prod" ..
	<html data-env="custom" ..		<html data-env="..custom.." ..

			The value used here is the normalised value, meaning if your appsettings originally specified "Production" then it would still be output as data-env="prod".

	For the same reasons as described above, Javascript and CSS should also minimise their environment variance as much as possible and favour configuration settings instead of code.		For the same reasons as described above, Javascript and CSS should also minimise their environment variance as much as possible and favour configuration settings instead of code.

Luke: /* Code varying by environment */

2023-04-25T17:24:59Z

Code varying by environment

← Older revision		Revision as of 17:24, 25 April 2023
Line 19:		Line 19:

	</syntaxhighlight>		</syntaxhighlight>


			On the frontend, Javascript and CSS can identify the current environment via the data-env-* attribute which is set on the <html> element:


			<html data-env-dev ..
			<html data-env-stage ..
			<html data-env-prod ..
			<html data-env="custom" ..

			For the same reasons as described above, Javascript and CSS should also minimise their environment variance as much as possible and favour configuration settings instead of code.

	= Best practises =		= Best practises =

Luke: /* Environment specific configuration */

2023-04-25T14:07:52Z

Environment specific configuration

← Older revision		Revision as of 14:07, 25 April 2023
Line 39:		Line 39:

	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.		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.

			Such environment varying configuration can also be used by Javascript via useConfig from UI/Configuration and marking the config in the API with the [Frontend] attribute.

Luke: /* Code varying by environment */

2023-04-25T13:52:26Z

Code varying by environment

← Older revision		Revision as of 13:52, 25 April 2023
Line 3:		Line 3:
	= Code varying by environment =		= 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:		This is best avoided for a reason which will be touched on shortly. If your code must vary by environment, you can use the Services class in the Api.Startup namespace:

	<syntaxhighlight lang="csharp">		<syntaxhighlight lang="csharp">

	using Api.~~Configuration~~;		using Api.Startup;


	~~Environment~~.IsProduction(); // true/ false		Services.IsProduction(); // true/ false

	~~Environment~~.IsStaging(); // true/ false		Services.IsStaging(); // true/ false

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

			Services.Environment // The raw original name from appsettings

	</syntaxhighlight>		</syntaxhighlight>

Luke: /* How a server knows which environment it is */

2023-04-25T13:44:02Z

How a server knows which environment it is

← Older revision		Revision as of 13:44, 25 April 2023
Line 27:		Line 27:

	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.		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.

			If you are doing environment specific code, it is strongly advised to edit your appsettings.json to make your development instance think it is the environments you are affecting to test the code whilst it is being written.

	= Environment specific configuration =		= Environment specific configuration =

Luke: Created page with "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 envir..."

2023-04-25T13:41:23Z

Created page with "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 envir..."

New page

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:

<syntaxhighlight lang="csharp">

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.

</syntaxhighlight>

= 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.