diff --git a/docs/self-hosted/installation.md b/docs/self-hosted/installation.md index a4ac5b9..72e7e3f 100644 --- a/docs/self-hosted/installation.md +++ b/docs/self-hosted/installation.md @@ -6,6 +6,12 @@ sidebar_position: 2 The overall installation of Resgrid is tailored to your specific usage scenarios and will require first procuring the required numbers of servers or VM's and continuing the installation process. If your department will have 50 or less users and units utilizing it at one time, we recommend using the Quick Start. +:::danger Warranty +Resgrid's self hosted version is provided with no warranty, no guarantee of suitability and limited free support (Github Issues and Discussions only). +Updates for our self hosted version are infrequent compared to our hosted version due to the additional cost in time to create those releases. We try +our best to ensure an easy and working system that doesn't require a lot of tweaking, but due to it's complexity that is difficult. +::: + ## Prerequisites Resgrid's recommended install is on Ubuntu 24.04 with Docker to meet the Small sizing install requirements you will need a minimum of 5 servers: diff --git a/docs/self-hosted/laptop.md b/docs/self-hosted/laptop.md index b415d4d..da2a4ea 100644 --- a/docs/self-hosted/laptop.md +++ b/docs/self-hosted/laptop.md @@ -6,6 +6,12 @@ sidebar_position: 3 In this guide we will get Resgrid up in running via Docker Compose for local (single user) use on a Windows computer. +:::danger Warranty +Resgrid's self hosted version is provided with no warranty, no guarantee of suitability and limited free support (Github Issues and Discussions only). +Updates for our self hosted version are infrequent compared to our hosted version due to the additional cost in time to create those releases. We try +our best to ensure an easy and working system that doesn't require a lot of tweaking, but due to it's complexity that is difficult. +::: + ## Use Case This setup is intended to get Resgrid up and running on a single-user environment, like a laptop that will not be connected to or have internet access. No external users (i.e. from another machine or mobile device) will be connecting to this installation. For example you are coordinate rescue and recovery efforts for a hurricane from a location on your laptop, you are communicate with your field teams only via a radio as there is no power or cell phone data/WiFi Internet. diff --git a/docs/self-hosted/quick-start.md b/docs/self-hosted/quick-start.md index 90a52b7..cc65f17 100644 --- a/docs/self-hosted/quick-start.md +++ b/docs/self-hosted/quick-start.md @@ -6,6 +6,12 @@ sidebar_position: 1 In this quick start we will get Resgrid up in running via Docker Compose for testing and evaluation. This quick start is valuable for getting the system up and running quickly for evaluation or testing purposed, but is not the recommended setup for production use. +:::danger Warranty +Resgrid's self hosted version is provided with no warranty, no guarantee of suitability and limited free support (Github Issues and Discussions only). +Updates for our self hosted version are infrequent compared to our hosted version due to the additional cost in time to create those releases. We try +our best to ensure an easy and working system that doesn't require a lot of tweaking, but due to it's complexity that is difficult. +::: + ## Prerequisites 1.) Server or VM that meets the System Requirements below @@ -73,7 +79,7 @@ We recommend using Docker (or Docker-CE) as the container system as it's what we Download and Extract Package -1. Clone the setup scripts for the all-in-one QuickStart: +Clone the setup scripts for the all-in-one QuickStart: ```bash git clone https://github.com/Resgrid/resgrid-setup.git resgrid @@ -81,33 +87,12 @@ git clone https://github.com/Resgrid/resgrid-setup.git resgrid You should now have a folder called resgrid in your current directory. -2. Open the resgrid directory: +Open the resgrid directory: ```bash cd resgrid ``` -3. Verify and Set mmap counts - -First run the command below to get your current mmap counts - -```bash -sysctl vm.max_map_count -``` - -If the value returned is less then 262144 run the following commands - -```bash -sudo sysctl -w vm.max_map_count=262144 -sudo nano /etc/sysctl.conf -``` - -Find the vm.max_map_count value and set to 262144 and save the file. If you can't find the value add it to the bottom of the file. - -``` -vm.max_map_count=262144 -``` - ## Setting Environment Variables Edit the environment file: @@ -155,22 +140,29 @@ The Resgrid Event Hub (5153) is a SignalR hub that utilized Web Sockets for real ## Run the Docker Compose -Once you have setup the environment variables you can now run the docker compose file.: +Once you have setup the environment variables you can now run the docker compose file: ```bash -docker compose up +./run.sh ``` -That will run the interactive version of the containers, Ctrl+C will stop the containers. +:::tip Note +The run script will require sudo. If you want to run without sudo just create a sql directory under the docker-data directory and you can use "docker compose up -d" command instead. +::: -If you want to run the containers in the background, use the -d option: +The Resgrid system will take about 5 minutes to start up fully, this is due to the startup order of the containers. The last container to startup will be the web container, once that one is ready, you can now access the system. + +To get log output you can run: ```bash -docker compose up -d +docker compose logs ``` -The Resgrid system will take about 5 minutes to start up fully, this is due to the startup order of the containers. The last container to startup will be the web container, once that one is ready, you can now access the system. +Or if you need to get output from a specific container just supply the name of the container from the docker-compose.yml file, for example: +```bash +docker compose logs worker +``` ## Important Note About Support diff --git a/docs/self-hosted/rick.md b/docs/self-hosted/rick.md new file mode 100644 index 0000000..bda826c --- /dev/null +++ b/docs/self-hosted/rick.md @@ -0,0 +1,136 @@ +--- +sidebar_position: 4 +--- + +# Offline Multi-User + +In this guide we will get Resgrid up in running in a Portable, Offline mode that + +:::danger Warranty +Resgrid's self hosted version is provided with no warranty, no guarantee of suitability and limited free support (Github Issues and Discussions only). +Updates for our self hosted version are infrequent compared to our hosted version due to the additional cost in time to create those releases. We try +our best to ensure an easy and working system that doesn't require a lot of tweaking, but due to it's complexity that is difficult. +::: + +## Use Case + +This setup is intended to get Resgrid up and running on a single-user environment, like a laptop that will not be connected to or have internet access. No external users (i.e. from another machine or mobile device) will be connecting to this installation. For example you are coordinate rescue and recovery efforts for a hurricane from a location on your laptop, you are communicate with your field teams only via a radio as there is no power or cell phone data/WiFi Internet. + +## System Requirements + +1.) Windows 10 or Windows 11 Laptop with WSL2 (Windows Subsystem for Linux) +2.) Docker Desktop with WSL2 Enabled +3.) Enough HDD Space to handle Mapping Data (if you want a large region like North America you'll need 30+ GB) +4.) 4 or more Core Processor +5.) 16GB or more of RAM + +## Setup Notice + +There is no redundancy, backup or fail-over in this setup. Everything runs on the local computer and is not intended to be accessed by anyone off of the local computer. If the local computer gets damaged this could result in loss of data. It's recommend that you have a USB drive that you can backup the database to (ideally the whole resgrid directory) periodically during the operation. + +## Prerequisites & Dependencies + +1. Update Windows +2. Install WSL2 and Ubuntu 22.04 +3. Open up your Ubuntu 22.04 instance and finalize the setup (set password). +4. Install Docker and enable WSL2 backend. + +## Docker Compose Setup + +1. Open Notepad as Administrator and open C:\Windows\System32\drivers\etc\hosts file. + +2. Add the following lines to the hosts file and save. +``` +127.0.0.1 rg.mylocal +127.0.0.1 rgapi.mylocal +127.0.0.1 rgevents.mylocal +127.0.0.1 rgtile.mylocal +``` + +If you get a permissions error you didn't open up Notepad as Administrator, also don't use any RichText editor (Wordpad, Word, etc). + +3. Navigate to Geofabrik and download the .osm.pbf file the region you will be operating in. + +It is not recommend to try and pull an entire Sub Region (i.e. North America) as that will take quite a long time to import into the database. Instead it's recommended to import and additional Sub (Sub) Region, like a US State (i.e. Florida) or a Special Sub Region if they are available (i.e. US South). + +4. Using the Windows File Explorer move the osm.pbf file into Linux (left side bar) Ubuntu-22.04, home and your username folder. This will put it in your home directory. + +5. Start your Ubuntu-22.04 WSL2 Instance so the command prompt is visible. + +6. Clone the setup scripts for the Laptop compose: + +```bash +git clone https://github.com/Resgrid/resgrid-setup.git -b laptop resgrid +``` + +You should now have a folder called resgrid in your current directory. + +7. Open the resgrid directory: + +```bash +cd resgrid +``` + +8. Import the osm.pbf you downloaded and placed in your home directory into the tile server. Change /home/yourname/yourregion.osm.pbf in the command below to the correct home directory name (yourname) and the name of the region file you downloaded (yourregion). + +```bash +docker run \ + -v /home/yourname/yourregion.osm.pbf:/data/region.osm.pbf \ + -v ./docker-data/osm:/data/database/ \ + overv/openstreetmap-tile-server \ + import +``` + +If the container exits without errors, then your data has been successfully imported and you are now ready to run the tile server. If you selected a very large region, like North America this process can take days. + + +## Run the Docker Compose + +Once you have setup the environment variables you can now run the docker compose file in the resgrid directory: + +```bash +docker compose up +``` + +That will run the interactive version of the containers, Ctrl+C will stop the containers. + +If you want to run the containers in the background, use the -d option: + +```bash +docker compose up -d +``` + +The Resgrid system will take about 5 minutes to start up fully, this is due to the startup order of the containers. The last container to startup will be the web container, once that one is ready, you can now access the system. + + +## Initial Web Login + +Open up your web browser and navigate to **https://rg.mylocal**, **https://rgapi.mylocal**, **https://rgevents.mylocal** and **https://rgtile.mylocal**. You will need to accept the self-signed cert for each url and add exceptions in the browsers. You can follow this guide to add those exceptions. + +Once you have completed the steps above you will be able to log into the web applications user interface. Open up a web browser and navigate to **https://rg.mylocal**, you will then be prompted by the login screen. Your default administrator credentials are **admin/changeme1234**. Once you log into the system it’s recommended that you change your admin password from the Edit Profile page by clicking on the Administrator name in the upper left hand corner. + +## Updating + +To update Resgrid you'll need to stop the system, clear the current containers and restart. + +Stop all running containers. + +```bash +docker compose down +``` + +Remove all cached images (to ensure we get new ones). + +```bash +docker rmi -f $(docker images -aq) +``` + +Restart the containers and they will pull new containers. + +```bash +docker compose up -d +``` + +## What's Next? + +This Quick Start gets the system running via local host, but not externally or within your network. You will need to create DNS entries in your internal or external DNS server to point to the server that is running the containers. It's also recommend you change some default values in the resgrid.env file to ensure proper security. \ No newline at end of file