docs/8.0/ayanova/docs/ops-install-linux-desktop.md

@@ -2,9 +2,9 @@
 
 The "desktop" installation is appropriate for a single user of AyaNova on a Linux x64 Desktop OS computer accessed with local browser.
 
-## Ubuntu
+## Linux distributions
 
-These instructions were compiled and tested on an Ubuntu 21.10 Desktop OS however any Linux x64 variant should work provided the ASP.NET Core framework can be installed to it.
+These instructions were compiled and tested on an Ubuntu 21.10 Desktop OS however any Linux x64 distribution should work provided the ASP.NET Core framework can be installed to it.
 
 ## System requirements
 
@@ -21,17 +21,17 @@ These instructions were compiled and tested on an Ubuntu 21.10 Desktop OS howeve
 AyaNova requires the ASP.NET Core runtime version 6.0 or newer.
 Install the ASP.NET CORE runtime using this guide for your specific OS [https://docs.microsoft.com/en-us/dotnet/core/install/linux](https://docs.microsoft.com/en-us/dotnet/core/install/linux)
 
-
 ### PostgreSQL server
 
-AyaNova requires access to a PostgreSQL database server version 12 or newer. If you do not have a PostgreSQL server already available then it must be installed to a location visible to the AyaNova server (same computer or a local computer on the same network). 
+AyaNova requires access to a PostgreSQL database server version 12 or newer. If you do not have a PostgreSQL server already available then it must be installed to a location visible to the AyaNova server (same computer or a local computer on the same network).
 
-We recommend *not* using the version of PostgreSQL provided by your OS package manager as they tend to be out of date.
+We recommend _not_ using the version of PostgreSQL provided by your OS package manager as they tend to be out of date.
 
 To install PostgreSQL directly start here [https://www.postgresql.org/download/linux/](https://www.postgresql.org/download/linux/)
 
 ### Set the PostgreSQL password
-If you are installing a local copy of PostgreSQL for the first time to use with AyaNova a password will need to be set for access.  If you have an existing PostgreSQL server then you can skip this step but will need the Postgre server password in a later step.
+
+If you are installing a local copy of PostgreSQL for the first time to use with AyaNova a password will need to be set for access. If you have an existing PostgreSQL server then you can skip this step but will need the Postgre server password in a later step.
 
 Open the terminal (ctrl-alt-t):
 Type `sudo -u postgres psql`
@@ -39,26 +39,75 @@ This should open a postgres psql command window
 Type `ALTER USER postgres PASSWORD 'YOUR_PASSWORD_HERE';` substituting your desired password here and be sure to make a note of it for later.
 If successful psql will display "ALTER ROLE" in response and you can close the psql terminal by typing `\q` to quit.
 
+### Create folders for AyaNova
 
-### AyaNova server installation
+AyaNova requires two folders to be created, one to hold the AyaNova binary and other server and web application files and one to hold the AyaNova data. AyaNova will need to write to both these locations so be sure you choose locations with appropriate permissions.
 
-Once you have ensured the two requirements above are installed and available; download the AyaNova server archive: [https://www.ayanova.com/Downloads/v8/ayanova-linux-x64-desktop.zip](https://www.ayanova.com/Downloads/v8/ayanova-linux-x64-desktop.zip). 
+From the terminal:
 
+Create the data folder, for desktop linux we recommend your user home folder and AyaNova defaults to '~/.ayanova-data' in it's configuration, however you can use any location that you have write access to.
+Type `sudo mkdir ~/.ayanova-data`
 
+Create the AyaNova binary files folder. For desktop linux we recommend `/usr/bin/ayanova`.
+Type `sudo mkdir /usr/bin/ayanova`
 
+### Download the AyaNova binaries archive
 
+[https://www.ayanova.com/Downloads/v8/ayanova-linux-x64-desktop.zip](https://www.ayanova.com/Downloads/v8/ayanova-linux-x64-desktop.zip)
 
+Download the the AyaNova server binary files folder created in the previous step or copy it there from the terminal:
+`sudo cp ayanova-linux-x64-desktop.zip /usr/bin/ayanova/`
 
+### Unzip the archive
 
+Unzip the archive into the AyaNova server binary files folder created in the previous step.
+Assuming it's located in the ayanova bin folder from the terminal:
+`sudo unzip ayanova-linux-x64-desktop.zip`
 
+### Set execute permission
 
-////////////////////////////////////////////////////
-- Download and run the standalone installer from our web site: [https://www.ayanova.com/Downloads/v8/ayanova-windows-x64-single-setup.exe](https://www.ayanova.com/Downloads/v8/ayanova-windows-x64-single-setup.exe). Follow the prompts and accept the defaults. At the end of setup the ayanova-launcher application will start if selected (or you can run it from the desktop icon) and in turn it will start the Postgres server, AyaNova server and then open the default web browser to both the AyaNova server interface and the AyaNova User interface.
+From the terminal in the AyaNova binary files folder:
+`sudo chmod 777 ./AyaNova`
+
+### Server configuration
+
+The server **must** be configured before it will be able to start properly and find the database server.
+
+The AyaNova bin folder has a `config.json` file is AyaNova's initial source for [configuration settings](ops-config-environment-variables.md) required for the server to start. It is necessary to edit this file (or provide an [alternative source of configuration](ops-config-environment-variables.md) and specify the password to connect to the PostgreSQL server. For example, if editing the default config.json file:
+
+```json
+{
+  "AYANOVA_USE_URLS": "http://*:7575",
+  "AYANOVA_DB_CONNECTION": "Server=localhost;Username=postgres;Password=mypasswordforpostgres;Database=AyaNova;",
+  "AYANOVA_DEFAULT_TRANSLATION": "en",
+  "AYANOVA_DATA_PATH": "~/.ayanova-data",
+  "AYANOVA_LOG_LEVEL": "Info"
+}
+```
+
+The `AYANOVA_DB_CONNECTION` property must be edited and where it has "mypasswordforpostgres" substitute the actual PostgreSQL password to be used that was previously set. If the database server is located on a different computer then the `Server=` connection string property must be set to the address of that computer.
+
+The `AYANOVA_USE_URLS` property specifies which TCP / IP Port that AyaNova server should listen on for connections from web browsers. The default value is port 7575 which should be free in most cases, however if you need to use an alternate port due to conflict it must be set here. We recommend using the default 7575 to avoid current or future confusion or conflict with other servers that may be installed or present elsewhere on the network.
+
+### Boot and test AyaNova server
+
+Start the server from the AyaNova bin folder in a terminal windows (ctrl-alt-t)
+`./AyaNova'
+
+You should see an output in the terminal that indicates the AyaNova server version and that it is booting. Any problems found that prevent boot up will be displayed here.
+
+If all is well then the console window will display "BOOT: COMPLETED - SERVER OPEN" as well as some other configuration data:
+
+![AyaNova server console running](img/ops-install-linux-console-open.png)
+
+### Login to AyaNova web app
+
+Open your web browser and navigate to the AyaNova server URL. Assuming the default port of 7575 is in use then the URL would be [http://localhost:7575](http://localhost:7575).
 
 ## Starting and stopping AyaNova server
 
-To shut down the AyaNova server press the ctrl-c key combination in the ayanova-launcher window.
-To start the AyaNova server use the installed desktop or start menu icon to run the ayanova-launcher.
+To shut down the AyaNova server cleanly use the AyaNova web app form accessed from Server Operations -> Server State and the menu item Shut down server.  
+Alternatively you can hard shut down AyaNova using the ctrl-c key combination in the terminal console window where AyaNova is running however this is not recommended.
 
 ## Getting started and using AyaNova