Merge pull request #1798 from pierotofy/impprof

Revamp docs, move information from README to docs

Author: pierotofy

README.md

@@ -18,23 +18,59 @@ export default defineConfig({
 			customCss: [
 				'./src/styles/custom.css',
 			],
-			social: [{ icon: 'github', label: 'GitHub', href: 'https://github.com/OpenDroneMap/WebODM' }],
+			social: [
+				{ icon: 'discourse', label: 'Community Forum', href: 'https://community.opendronemap.org' },
+				{ icon: 'github', label: 'GitHub', href: 'https://github.com/OpenDroneMap/WebODM' }
+			],
 			sidebar: [
 				{
-					label: 'Quickstart',
-					slug: 'quickstart'
+					label: 'Installation',
+					slug: 'installation'
+				},
+				{
+					label: 'Hardware Requirements',
+					slug: 'hardware-requirements'
+				},
+				{
+					label: 'Common Tasks',
+					slug: 'common-tasks'
 				},
 				{
-					label: 'Reference',
-					autogenerate: { directory: 'reference' },
+					label: 'Frequently Asked Questions',
+					slug: 'faq'
 				},
 				{
-					label: 'Contributing',
-					slug: 'contributing'
+					label: 'Support the Project',
+					slug: 'support-the-project'
 				},
 				{
-					label: 'Plugin Development Guide',
-					slug: 'plugin-development-guide'
+					label: 'Developers',
+					items: [
+						{
+							label: 'Contributing',
+							slug: 'contributing'
+						},
+						{
+							label: 'Architecture',
+							slug: 'architecture'
+						},
+						{
+							label: 'Roadmap',
+							slug: 'roadmap'
+						},
+						{
+							label: 'Plugin Development Guide',
+							slug: 'plugin-development-guide'
+						},
+						{
+							label: 'API Quickstart',
+							slug: 'quickstart'
+						},
+						{
+							label: 'API Reference',
+							autogenerate: { directory: 'reference' },
+						},
+					]
 				},
 			],
 		}),

contrib/Hard_Recovery_Guide.md

@@ -0,0 +1,20 @@
+---
+title: Architecture
+template: doc
+---
+
+The [OpenDroneMap project](https://github.com/OpenDroneMap/) is composed of several components.
+
+- [ODM](https://github.com/OpenDroneMap/ODM) is a command line toolkit that processes aerial images. Users comfortable with the command line are probably OK using this component alone.
+- [NodeODM](https://github.com/OpenDroneMap/NodeODM) is a lightweight interface and API (Application Program Interface) built directly on top of [ODM](https://github.com/OpenDroneMap/ODM). Users not comfortable with the command line can use this interface to process aerial images and developers can use the API to build applications. Features such as user authentication, map displays, etc. are not provided.
+- [WebODM](https://github.com/OpenDroneMap/WebODM) adds more features such as user authentication, map displays, 3D displays, a higher level API and the ability to orchestrate multiple processing nodes (run jobs in parallel). Processing nodes are simply servers running [NodeODM](https://github.com/OpenDroneMap/NodeODM).
+
+![webodm](https://cloud.githubusercontent.com/assets/1951843/25567386/5aeec7aa-2dba-11e7-9169-aca97b70db79.png)
+
+WebODM is built with scalability and performance in mind. While the default setup places all databases and applications on the same machine, users can separate its components for increased performance (ex. place a Celery worker on a separate machine for running background tasks).
+
+![Architecture](https://user-images.githubusercontent.com/1951843/36916884-3a269a7a-1e23-11e8-997a-a57cd6ca7950.png)
+
+A few things to note:
+ * We use Celery workers to do background tasks such as resizing images and processing task results, but we use an ad-hoc scheduling mechanism to communicate with NodeODM (which processes the orthophotos, 3D models, etc.). The choice to use two separate systems for task scheduling is due to the flexibility that an ad-hoc mechanism gives us for certain operations (capture task output, persistent data and ability to restart tasks mid-way, communication via REST calls, etc.).
+ * If loaded on multiple machines, Celery workers should all share their `app/media` directory with the Django application (via network shares). You can manage workers via `./worker.sh`

contrib/ubuntu_1604_install.sh

@@ -0,0 +1,56 @@
+---
+title: Common Tasks
+template: doc
+---
+
+It's fairly straightforward to manage an installation of WebODM. Here's a list of common operations you might need to do:
+
+## Reset Admin Password
+
+If you forgot the password you picked the first time you logged into WebODM, to reset it just type:
+
+```bash
+./webodm.sh start && ./webodm.sh resetadminpassword newpass
+```
+
+The password will be reset to `newpass`. The command will also tell you what username you chose.
+
+## Backup and Restore
+
+If you want to move WebODM to another system, you just need to transfer the docker volumes (unless you are storing your files on the file system).
+
+On the old system:
+
+```bash
+mkdir -v backup
+docker run --rm --volume webodm_dbdata:/temp --volume `pwd`/backup:/backup ubuntu tar cvf /backup/dbdata.tar /temp
+docker run --rm --volume webodm_appmedia:/temp --volume `pwd`/backup:/backup ubuntu tar cvf /backup/appmedia.tar /temp
+```
+
+Your backup files will be stored in the newly created `backup` directory. Transfer the `backup` directory to the new system, then on the new system:
+
+```bash
+ls backup # --> appmedia.tar  dbdata.tar
+./webodm.sh down # Make sure WebODM is down
+docker run --rm --volume webodm_dbdata:/temp --volume `pwd`/backup:/backup ubuntu bash -c "rm -fr /temp/* && tar xvf /backup/dbdata.tar"
+docker run --rm --volume webodm_appmedia:/temp --volume `pwd`/backup:/backup ubuntu bash -c "rm -fr /temp/* && tar xvf /backup/appmedia.tar"
+./webodm.sh start
+```
+
+## Update
+
+If you use docker, updating is as simple as running:
+
+```bash
+./webodm.sh update
+```
+
+## Customizing and Extending
+
+Small customizations such as changing the application colors, name, logo, or adding custom CSS/HTML/Javascript can be performed directly from the Customize -- Brand/Theme panels within WebODM. No need to fork or change the code.
+
+More advanced customizations can be achieved by [writing plugins](/plugin-development-guide/). This is the preferred way to add new functionality to WebODM since it requires less effort than maintaining a separate fork. The plugin system features server-side signals that can be used to be notified of various events, a ES6/React build system, a dynamic client-side API for adding elements to the UI, a built-in data store, an async task runner, hooks to add menu items and functions to rapidly inject CSS, Javascript and Django views.
+
+To learn more, start from the [plugin development guide](https://docs.webodm.org/plugin-development-guide/). It's also helpful to study the source code of [existing plugins](https://github.com/OpenDroneMap/WebODM/tree/master/coreplugins).
+
+If a particular hook / signal for your plugin does not yet exist, [request it](https://github.com/OpenDroneMap/WebODM/issues). We are adding hooks and signals as we go.

docs/astro.config.mjs

@@ -0,0 +1,20 @@
+---
+title: Frequently Asked Questions
+template: doc
+---
+
+## Where Are My Files Stored?
+
+When using Docker, all processing results are stored in a docker volume and are not available on the host filesystem. There are two specific docker volumes of interest:
+1. Media (called webodm_appmedia): This is where all files related to a project and task are stored.
+2. Postgres DB (called webodm_dbdata): This is what Postgres database uses to store its data.
+
+For more information on how these two volumes are used and in which containers, please refer to the [docker-compose.yml](docker-compose.yml) file.
+
+For various reasons such as ease of backup/restore, if you want to store your files on the host filesystem instead of a docker volume, you need to pass a path via the `--media-dir` and/or the `--db-dir` options:
+
+```bash
+./webodm.sh restart --media-dir /home/user/webodm_data --db-dir /home/user/webodm_db
+```
+
+Note that existing task results will not be available after the change. Refer to the [Migrate Data Volumes](https://docs.docker.com/engine/tutorials/dockervolumes/#backup-restore-or-migrate-data-volumes) section of the Docker documentation for information on migrating existing task results.

docs/src/content/docs/architecture.md

@@ -0,0 +1,33 @@
+---
+title: Hardware Requirements
+template: doc
+---
+
+To run a standalone installation of WebODM (the user interface), including the processing component ([NodeODM](https://github.com/OpenDroneMap/NodeODM)), we recommend at a minimum:
+
+* 100 GB free disk space
+* 16 GB RAM
+
+Don't expect to process more than a few hundred images with these specifications. To process larger datasets, add more RAM linearly to the number of images you want to process:
+
+| Number of Images | RAM or RAM + Swap (GB) |
+| ---------------- | ---------------------- |
+| 40               | 4                      |
+| 250              | 16                     |
+| 500              | 32                     |
+| 1500             | 64                     |
+| 2500             | 128                    |
+| 3500             | 192                    |
+| 5000             | 256                    |
+
+:::note
+
+These are conservative estimates. A lot of factors influence memory usage, such as image dimensions, flight altitude and processing settings. So you might be able to process more images with less memory than reported above.
+
+:::
+
+A CPU with more cores will speed up processing, but can increase memory usage. GPU acceleration is also supported on Linux and WSL. To make use of your CUDA-compatible graphics card, make sure to pass `--gpu` when starting WebODM. You need the nvidia-docker installed in this case, see https://github.com/NVIDIA/nvidia-docker and https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/install-guide.html#docker for information on docker/NVIDIA setup.
+
+WebODM runs best on Linux, but works well on Windows and Mac too.
+
+WebODM by itself is just a user interface and does not require many resources. WebODM can be loaded on a machine with just 1 or 2 GB of RAM and work fine without [NodeODM](https://github.com/OpenDroneMap/NodeODM). You can use a processing service such as [webodm.net](https://webodm.net) or run NodeODM on a separate, more powerful machine.