update readme, install

INSTALL.md

@@ -1,89 +1,118 @@
 # Install Blawx
 
-The recommended method of installing and running Blawx is with Docker.
+Blawx is developed as a docker container, and is most easily deployed as a docker container.
+A pre-built container image is available on docker hub, or you can build an image locally from the source files.
 
 ## Install Docker
 
 Install Docker for the platform you are using.
 
-## Clone Blawx
+## Install Blawx
+
+### Install from Docker Image
+
+The easiest way to run Blawx is to enter the command `docker run lexpedite/blawx`, or to use your docker application to run
+the `lexpedite/blawx` image.
+
+The Blawx server will now be available at [http://127.0.0.1:8000](http://127.0.0.1:8000),
+and the administrative console will be available at [http://127.0.0.1:8000/admin](http://127.0.0.1:8000/admin).
+
+You can log into the admin console using the username "admin" and the password "blawx2022", which should be
+changed immediately on logging in.
+
+### Install from Source
 
 Using git, clone this repository to your local machine.
 ```
 git clone https://github.com/Lexpedite/blawx blawx
 ```
 
-## Build and Run Blawx
-
-Build the blawx image with the following commands
+Build the blawx image using these commands... (this is only required only once per installation or upgrade)
 ```
 cd blawx
-./update.sh
+docker build -t blawx .
 ```
 
-Note that the `./update.sh` script runs the blawx server in the terminal, for development purposes, so that you can see debug information.
-If you want to run the docker container in the background, add `-d` as a flag to the `docker run` command in that script.
-
-This command will take several minutes to run the first time.
-
-The Blawx server will now be available at [http://127.0.0.1:8000](http://127.0.0.1:8000),
-and the administrative console will be available at [http://127.0.0.1:8000/admin](http://127.0.0.1:8000/admin).
-
-You can log into the admin console using the username "admin" and the password "blawx2022", which should be
-changed immediately on logging in. 
-
-If you would like to configure the name of the admin user, you can do that by changing the default value
-in the Dockerfile, or by providing the flag `--build-arg SU_PASSWORD=password` to `docker build` instead
-of running the `./update.sh` script.
+Optionally, you can provide the `--build-arg SU_PASSWORD=password` flag on the docker build command to set the admin password at build time to avoid the default.
 
-A demo account with username "demo" and password "blawx2022" is also created,
-and should be deleted in the admin interface if you want to restrict access to your server.
+Run the blawx image using this command (or using the Docker graphical interface)
+```
+docker run -it -p 8000:8000 blawx
+```
 
-## Configure ChatGPT Integration
+## Configuring ChatGPT Integration
 
 If you wish to run Blawx with ChatGPT integration, which allows for AI-generated summaries of explanations to be displayed
-to the user in the scenario editor, you will need to not use the `./update.sh` command, and instead enter these two commands:
+to the user in the scenario editor, modify the docker run command as follows (or do the equivalent in the docker interface of your choice).
 
 ```
-docker build -t blawx .
 docker run -it -p 8000:8000 -e OPENAI_API_KEY="your_key_goes_here" blawx
 ```
 
 ## Updating Blawx
 
-Blawx is under active development. Currently, updates are being sent to GitHub only, there is no published
-python module or docker container. In order to run the most recent version of Blawx, go to the directory
-in which you installed it, and run these commands:
+Blawx is under active development, and changes to Blawx may not be reverse compatible with prior versions. Please refer to the
+CHANGELOG.md before updating.
 
-```
-git pull
-./update.sh
-```
+To update the published docker image, use `docker pull lexpedite/blawx`.
 
-Occasionally, there are changes made to Blawx that require a fresh install of other dependencies.
-Whenever that is the case, it will be mentioned in the [changelog](CHANGELOG.md). If a full
-re-install is required, then you should instead perform these steps:
+To update the source, use `git pull` in the source folder, and re-build the image.
 
-```
-git pull
-docker stop $(docker ps -qf "ancestor=blawx")
-docker build --no-cache -t blawx .
-./update.sh
-```
+Stop the existing image if it is still running, and run the new image.
+
+Occasionally, there are changes made to Blawx that require a fresh install dependencies but are not detected by docker when
+installing from source code. If that is the case, it will usually be noted in the [changelog](CHANGELOG.md). 
+If a fresh build is required, add the `--no-cache` flag to the `docker build` command.
 
 ## Deployment
 
 Blawx is alpha software that should not be used for production purposes. However, if you want to deploy
 it in a public or shared environment for learning or experimental purposes,
-the provided docker configuration may not be appropriate. Instead,
+the provided docker configuration is not appropriate. Instead,
 it should be modified to follow the process for deploying a Django app. See [the Django documentation](https://docs.djangoproject.com/en/4.0/howto/deployment/)
 for more details.
 
-Steps for deploying will include:
+Steps for deploying will include at a minimum:
 * changing the server_name settings in the settings.py file
 * changing the DEBUG setting in the settings.py file
 * adding configurations for secure CRSF and Cookies in the settings.py file
 * configuring nginx or another proxy server to directly serve static files
 * configuring TLS
 * replacing the manage.py runserver with a production WSGI web server
-* replacing the CORS configuration (which is open by default) with a whitelist
+* replacing the CORS configuration (which is open by default) with a whitelist
+
+## Integration with Other Containers
+
+If you are deploying Blawx as a container in a docker compose configuration, it is often useful to have certain .blawx files
+pre-loaded and published when your Blawx server starts. This can be accomplished in a docker-compose.yml file by following these steps:
+
+1. Export the published `.blawx` files that you want deployed from a single Blawx server, or manually edit the files to ensure that each
+   uses a different primary key for each RuleDoc element.
+2. Change the extension of the `.blawx` files to `.yaml`.
+3. Place the files in a folder in your compose project, like `blawx/fixtures`.
+4. Create a volume that links this folder to the fixtures folder inside your blawx server, like this:
+```
+services:
+  blawx:
+    container_name: blawx_server
+    image: lexpedite/blawx
+    ports: 
+      - "8000:8000"
+    volumes:
+      - ./blawx/fixtures:/app/blawx/blawx/fixtures
+```
+5. Add a `command` that will load the files in that folder before running the server, like this:
+```
+services:
+  blawx:
+    container_name: blawx_server
+    image: lexpedite/blawx
+    ports: 
+      - "8000:8000"
+    volumes:
+      - ./blawx/fixtures:/app/blawx/blawx/fixtures
+    command: ["sh", "-c", "python3 manage.py loaddata blawx/fixtures/nrcan-map/*.yaml && python manage.py runserver 0.0.0.0:8000"]
+```
+
+Note that your command for running the server may not be `python manage.py runserver 0.0.0.0:8000`,
+and should be updated to match whatever command you are using to run your blawx server in production.

README.md

@@ -4,14 +4,14 @@ A user-friendly web-based tool for Rules as Code written by Jason Morris of [Lex
 
 Blocks + law = Blawx
 
-![Blawx Front End Screenshot](blawx_v1.3.16-alpha_screenshot.png)
+![Blawx Front End Screenshot](blawx_v1.6.16-alpha_interface.png)
 
 ## Demonstration Video
 
-Click on the thumbnail below for a recent (but probably not 100% up to date)
+Click on the thumbnail below for a recent
 video demonstration of how Blawx is used.
 
-[![thumbnail](thumbnail.png)](https://youtu.be/d2sxlvU9hlo)
+[![thumbnail](thumbnail.png)](https://youtu.be/x5l4Ynfr4VU)
 
 ## Overview
 
@@ -44,25 +44,30 @@ It provides:
 * Publish Code as an API
 * Explainability
 * Hypothetical reasoning
-* Automatically-generated Expert Systems
+* User-friendly Scenario Explorer
 
-As of v1.3.16-alpha, Blawx is the only open source Rules as Code programming environment with
-automatic chatbot-style expert systems, explanations for answers, and hypothetical reasoning.
+Blawx is the only open source Rules as Code programming environment with
+a user-friendly scenario explorer, explanations for answers, and hypothetical reasoning.
 
 ## How Can I Try It?
-The easiest way to try Blawx is to go to [www.blawx.com](https://www.blawx.com). I try to keep a recent version running there for people to play with.
+The easiest way to try Blawx is to go to [dev.blawx.com](https://dev.blawx.com). I try to keep a recent version running there for people to play with.
 
 ## How do I Install It Myself?
-If you would like to try running Blawx locally, check out [INSTALL.md](INSTALL.md) for instructions.
+If you would like to try running Blawx locally, install docker for your platform, and then run
+```
+docker run lexpedite/blawx
+```
+Blawx will then be available at (http://localhost:8000)[http://localhost:8000].
+
+Check out [INSTALL.md](INSTALL.md) for more details.
 
 ## How Can I Learn More?
-Extensive documentation, including the Blawx Beginner's Guide and several examples, is available from inside the application
-by clicking "Help" in the coding interface. You can also view the [documentation on the live demo site](https://dev.blawx.com/docs).
+Extensive documentation is available from inside the application
+by clicking "Help" in the left navigation menu. You can also view the [documentation on the live demo site](https://dev.blawx.com/docs).
 
 ## Is this software production ready?
-No. Blawx is functional, but it is not production-quality software. It is a proof of concept that is intended to motivate
-investment in similar technologies in the future by demonstrating what they are capable of.
+No. Blawx is functional, but it is not production-quality software. It is intended for educational and experimental purposes.
 
 ## Contributions
-If you have issues or concerns with the package, please open an Issue here in the [GitHub Repository](https://github.com/Lexpedite/blawx).
+If you have issues or concerns with the package, please open an Issue in the [GitHub Repository](https://github.com/Lexpedite/blawx).
 Contributions to the code and documentation are welcome. Please contribute responsibly.