Update DEVELOPING.md (#164)

* Update DEVELOPING.md

Added detailed guidance for getting the project up and running.

* Update DEVELOPING.md

Wording tweaks as per Rob's comments

* Update DEVELOPING.md

* Update README.md

---------

Co-authored-by: Rob Quincey <109682469+RobQuincey-DC@users.noreply.github.com>

DEVELOPING.md

@@ -1,12 +1,12 @@
 ## Dependencies
 To run GIFrameworkMaps with minimal modification, you will need.
-- A web server capable of running .NET 6 applications, such as IIS, Kestral or Azure (locally IIS Express or Kestral should be fine)
+- A web server capable of running .NET 7 applications, such as IIS, Kestral or Azure (locally IIS Express or Kestral should be fine). Linux servers can use Kestral via an Nginx proxy.
 - PostgresSQL 13+ with PostGIS extension
 
 ## Get Started
-- Clone the repository. The `main` branch should always be the latest, stable version. The `develop`
+- Clone the repository - the `main` branch should always be the latest, stable version
 - Create a user in your database with permission to create schemas and login
-- Set up your connection strings and user secrets (TODO - Document/Script this)
+- Set up your connection strings and user secrets
 - Run the Entity Framework migrations
     - Using Visual Studio
         - `Update-Database`
@@ -21,5 +21,89 @@ This will give you a minimal starting application, with a few basic basemaps, to
 either directly or by using the adminstration functions in the application to start adding layers, basemaps, versions and so on.
 
 ## Detailed guidelines
+First, clone the repositiry - the `main` branch should always be the latest, stable version.
 
-TODO
+### Setting up a database
+To run the project locally you will need to create a suitable database. Postgres is the only database provider currently set up, but with minimal adjustments you could make it use any Entity Framework compatible provider. Install the PostGIS extension to enable geometries in Postgres. 
+
+In your database, create a user for Entity Framework to use and give it permission to login and create databases.
+
+Create a schema within your database called giframeworkmaps. To avoid complex permissions, make the user account you created the owner of the schema.
+
+### User secrets and connection strings
+Once you’ve set up your database, add a user secret to your local copy of the application. In Visual Studio this is done by right-clicking on the web project and selecting “Manage user secrets”.
+
+In user secrets add the below line of code and fill in your database name, username and password:
+
+`{
+"ConnectionStrings:GIFrameworkMaps": "Host=localhost;Database=YourDatabaseName;Username=YourUserName;Password=YourPassword;SearchPath=giframeworkmaps"
+}`
+
+You should now be able to test your connection and run migrations using Entity Framework commands.
+
+You can choose to use appSettings or Environment Variables to store your secrets if you prefer. Azure KeyVault is also available with a few configuration settings, and is recommended for production scenarios.
+
+### Download optional extensions in Visual Studio
+There are two extensions we use in Visual Studio that you can download: 
+- NPM Task Runner
+- EF Core Power Tools 
+
+It's entirely optional to download these extensions. You can download these by going to the Extensions menu and then to Manage Extensions. You’ll need to restart Visual Studio once you’ve downloaded them.
+
+### Running the application
+Once you’ve followed the steps above, you’re ready to run the application. 
+
+- Run the Entity Framework migrations to create the empty tables in your database
+    - Using Visual Studio
+        - `Update-Database`
+    - Using .Net CLI
+        - `dotnet ef database update`
+- Run an `npm update` to download the dependencies
+    - In Visual Studio this can be done by installing the NPM Task Runner Extension and using Task Runner Explorer
+    - Alternatively just use the command line
+- Build and Run!
+
+This will give you a minimal starting application, with a few basic basemaps, to get you started. Start modifying your database either directly or by using the adminstration functions in the application to start adding layers, basemaps, versions and so on.
+
+### Authentication
+Follow these instructions if you want your app to have authentication so that permitted users can access the administration part of the site.
+
+Currently this app only supports Microsoft Azure AD B2C authentication. Refer to the official documentation to set this up in your project.
+
+Once you've got a service set up, you'll need to add a number of settings to your user secrets to enable it.
+
+```
+"AzureAd": {
+  "Instance": "https://<your-instance-name>.b2clogin.com",
+  "Domain": "<your-b2c-domain>",
+  "ClientId": "<your-client-id>",
+  "TenantId": "<your-tenant-id>",
+  "ClientSecret": "<your-client-secret>",
+  "SignedOutCallbackPath": "<your-signout-callback-path>",
+  "SignUpSignInPolicyId": "<your-sign-in-policy-id>"
+}
+```
+
+Go to your database and add a row to `ApplicationRoles` called `GIFWAdmin`. This is the role that has access to the administrative back-end. 
+
+You'll then need to login to your instance in order to retrieve your User ID. Run the application, log in and go to https://<your-application-root>/Account. The User ID will be shown on this page.
+
+Go back to your database, and add a row to `ApplicationUserRoles` with the `UserId` set to your User ID, and the `ApplicationRoleId` set to the ID of the `GIFWAdmin` role you added. You should now have administrative priviliges to the application (you may need to log out and back in)
+
+### Enabling KeyVault
+
+Azure KeyVault is available for secure storage of secrets in production environments.
+
+To set up KeyVault, [follow the instructions on the Microsoft website](https://learn.microsoft.com/en-us/aspnet/core/security/key-vault-configuration?view=aspnetcore-7.0#secret-storage-in-the-production-environment-with-azure-key-vault).
+
+You will then need the following settings in your Environment Variables or appSettings
+
+```
+  "KeyVault:AzureAd:ApplicationId": "<your-azure-app-id>",
+  "KeyVault:AzureAd:CertificateThumbprint": "<your-certificate-thumbprint>",
+  "KeyVault:AzureAd:DirectoryId": "<your-azure-directory-id>",
+  "KeyVault:Name": "<your-keyvault-name>",
+```
+
+### Further help
+For further information and help on configuring the service contact the core developers or leave a message for us in the Discussions section. We might not be able to get back to you straight away and in some cases we may need to charge for this service if your setup is complex or requires a formal agreement.

README.md

@@ -11,9 +11,6 @@ It is used by Dorset Council as their primary web mapping application for staff
 
 GIFrameworkMaps is Free and Open Source software, it uses [OpenLayers](https://openlayers.org/) and [Bootstrap](https://getbootstrap.com/), as well as many other libraries, and is licensed under the MIT licence.
 
-## Features
-TODO
-
 ## Bugs
 
 Please use the [GitHub issue tracker](https://github.com/Dorset-Council-UK/GIFramework-Maps/issues) for all bugs and feature requests. Before creating a new issue, do a quick search to see if the problem has been reported already.
@@ -25,7 +22,7 @@ To run GIFrameworkMaps with minimal modification, you will need.
 - A web server capable of running .NET applications, such as IIS, Kestral or Azure
 - PostgreSQL 13+ with PostGIS extension
 
-GIFrameworkMaps uses [Entity Framework Core](https://docs.microsoft.com/en-us/ef/core/), so any spatial database that has an Entity Framework Core provider should work, but this has not been tested. For a full list of providers, check the [Entity Framework docs](https://docs.microsoft.com/en-us/ef/core/providers/?tabs=dotnet-core-cli).
+GIFrameworkMaps uses [Entity Framework Core](https://docs.microsoft.com/en-us/ef/core/). Postgres has been set up for this project, but with some modifications, any Entity Framework Core compatible provider should work. For a full list of providers, check the [Entity Framework docs](https://docs.microsoft.com/en-us/ef/core/providers/?tabs=dotnet-core-cli).
 
 ## Contributing