diff --git a/docs/source/daemons.rst b/docs/source/daemons.rst index f7f2a25..fc6ed02 100644 --- a/docs/source/daemons.rst +++ b/docs/source/daemons.rst @@ -1,76 +1,22 @@ Daemons ===== -.. _installation: +The Daemon page is used the set the Service options. -Installation +Options ------------ -To use Lumache, first install it using pip: +There are four options for Daemons, as shown below: +.. image:: images/admin-14.png -Creating recipes ----------------- +Skip Init: Use Skip Init to skip the initialization of syncronization. -.. image:: images/daemons.png -now -Dashboard.png -images -now -daemons.png -images -now -data-1.png -images -now -data-2.png -images -now -data-3.png -images -now -data-4.png -images -now -geoserver-1.png -images -now -groups.png -images -now -project-1.png -images -now -project-2.png -images -now -project-3.png -images -now -servers.png -images -now -services.png -images -now -users.png +Force Init: Force Init will drop the PostGIS schema and reinitialize the Project in the database. +Single Run: Peform a single run. +Sleep Time: The Frequency determines how often the service syncronizes. By default, this is every 10 seconds. You can adjust this interval here using the slide. -To retrieve a list of random ingredients, -you can use the ``lumache.get_random_ingredients()`` function: - -.. autofunction:: lumache.get_random_ingredients - -The ``kind`` parameter should be either ``"meat"``, ``"fish"``, -or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients` -will raise an exception. - -.. autoexception:: lumache.InvalidKindError - -For example: - ->>> import lumache ->>> lumache.get_random_ingredients() -['shells', 'gorgonzola', 'parsley'] +NOTE: You must restart the instance for the above changes to take effect. diff --git a/docs/source/dashboard.rst b/docs/source/dashboard.rst index 1316af6..0105e66 100644 --- a/docs/source/dashboard.rst +++ b/docs/source/dashboard.rst @@ -1,34 +1,12 @@ Dashboard ===== -.. _installation: +The Dashboard can be accessed by clicking the "Administration" link at top once logged in. -Installation +Usage ------------ -To use Lumache, first install it using pip: +The Dashboard provides links to services as well as links to Documentation and Support. -.. code-block:: console - - (.venv) $ pip install lumache - -Creating recipes ----------------- - -To retrieve a list of random ingredients, -you can use the ``lumache.get_random_ingredients()`` function: - -.. autofunction:: lumache.get_random_ingredients - -The ``kind`` parameter should be either ``"meat"``, ``"fish"``, -or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients` -will raise an exception. - -.. autoexception:: lumache.InvalidKindError - -For example: - ->>> import lumache ->>> lumache.get_random_ingredients() -['shells', 'gorgonzola', 'parsley'] + .. image:: images/admin-2.png diff --git a/docs/source/data.rst b/docs/source/data.rst index 091c7c1..4c35c8a 100644 --- a/docs/source/data.rst +++ b/docs/source/data.rst @@ -1,34 +1,36 @@ Data ===== -.. _installation: +The Data page displays Project data in both tabular and map formats. -Installation +It also includes ability to Search, Query, Cluster, and Export to CVS + +Usage ------------ -To use Lumache, first install it using pip: +On the Data page, click the Project you wish to view as shown below: -.. code-block:: console + .. image:: images/admin-15.png - (.venv) $ pip install lumache -Creating recipes ----------------- +The data is displayed as a map and table. -To retrieve a list of random ingredients, -you can use the ``lumache.get_random_ingredients()`` function: +The Table can be sorted by column as well as searched. -.. autofunction:: lumache.get_random_ingredients -The ``kind`` parameter should be either ``"meat"``, ``"fish"``, -or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients` -will raise an exception. + .. image:: images/data-2.png -.. autoexception:: lumache.InvalidKindError -For example: +To export data to a CSV file, click the CSV links as shown below: ->>> import lumache ->>> lumache.get_random_ingredients() -['shells', 'gorgonzola', 'parsley'] + + .. image:: images/data-4.png + + + + +Multiple GeoPackages +------------ + +A data link will be displayed for each GeoPackage contained in a Project. diff --git a/docs/source/frontend.rst b/docs/source/frontend.rst index 01a7690..ad564fe 100644 --- a/docs/source/frontend.rst +++ b/docs/source/frontend.rst @@ -1,34 +1,10 @@ Front End ===== -.. _installation: +The Front End is identical in functionality to the Data page. -Installation ------------- +The Front End, however, is for End Users to view data only and does not contain links or access to the Administration area. -To use Lumache, first install it using pip: -.. code-block:: console - - (.venv) $ pip install lumache - -Creating recipes ----------------- - -To retrieve a list of random ingredients, -you can use the ``lumache.get_random_ingredients()`` function: - -.. autofunction:: lumache.get_random_ingredients - -The ``kind`` parameter should be either ``"meat"``, ``"fish"``, -or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients` -will raise an exception. - -.. autoexception:: lumache.InvalidKindError - -For example: - ->>> import lumache ->>> lumache.get_random_ingredients() -['shells', 'gorgonzola', 'parsley'] + .. image:: images/admin-17.png diff --git a/docs/source/geoserver.rst b/docs/source/geoserver.rst index 988a99c..c7d57ea 100644 --- a/docs/source/geoserver.rst +++ b/docs/source/geoserver.rst @@ -1,34 +1,15 @@ GeoServer ===== -.. _installation: +The GeoServer page allows you to create GeoServer PostGIS Stores from your PostGIS databases. -Installation +If the Workspace does not exist, it will be created. + +Usage ------------ -To use Lumache, first install it using pip: +Populate the required fields as shown below: -.. code-block:: console + .. image:: images/geoserver-1.png - (.venv) $ pip install lumache - -Creating recipes ----------------- - -To retrieve a list of random ingredients, -you can use the ``lumache.get_random_ingredients()`` function: - -.. autofunction:: lumache.get_random_ingredients - -The ``kind`` parameter should be either ``"meat"``, ``"fish"``, -or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients` -will raise an exception. - -.. autoexception:: lumache.InvalidKindError - -For example: - ->>> import lumache ->>> lumache.get_random_ingredients() -['shells', 'gorgonzola', 'parsley'] diff --git a/docs/source/groups.rst b/docs/source/groups.rst index 0411a53..4be2b64 100644 --- a/docs/source/groups.rst +++ b/docs/source/groups.rst @@ -1,34 +1,21 @@ Groups ===== -.. _installation: +The Groups page is used to group Projects together for viewing Project data via the Data and Front End pages. -Installation +Usage ------------ -To use Lumache, first install it using pip: +To create a Group, click the "Add New" button at top. -.. code-block:: console +Enter a name for the Group. - (.venv) $ pip install lumache +Use the Multi-Select element to select the Projects to include in your Group. -Creating recipes ----------------- -To retrieve a list of random ingredients, -you can use the ``lumache.get_random_ingredients()`` function: + .. image:: images/groups.png -.. autofunction:: lumache.get_random_ingredients - -The ``kind`` parameter should be either ``"meat"``, ``"fish"``, -or ``"veggies"``. Otherwise, :py:func:`lumache.get_random_ingredients` -will raise an exception. - -.. autoexception:: lumache.InvalidKindError - -For example: - ->>> import lumache ->>> lumache.get_random_ingredients() -['shells', 'gorgonzola', 'parsley'] +Actions +------------ +The Action buttons at right can be used to edit and delete Groups. diff --git a/docs/source/images/admin-1.png b/docs/source/images/admin-1.png new file mode 100644 index 0000000..9db01f7 Binary files /dev/null and b/docs/source/images/admin-1.png differ diff --git a/docs/source/images/admin-10.png b/docs/source/images/admin-10.png new file mode 100644 index 0000000..f65cf29 Binary files /dev/null and b/docs/source/images/admin-10.png differ diff --git a/docs/source/images/admin-11.png b/docs/source/images/admin-11.png new file mode 100644 index 0000000..4adba73 Binary files /dev/null and b/docs/source/images/admin-11.png differ diff --git a/docs/source/images/admin-12.png b/docs/source/images/admin-12.png new file mode 100644 index 0000000..b93d65d Binary files /dev/null and b/docs/source/images/admin-12.png differ diff --git a/docs/source/images/admin-13.png b/docs/source/images/admin-13.png new file mode 100644 index 0000000..bb999d8 Binary files /dev/null and b/docs/source/images/admin-13.png differ diff --git a/docs/source/images/admin-14.png b/docs/source/images/admin-14.png new file mode 100644 index 0000000..0447659 Binary files /dev/null and b/docs/source/images/admin-14.png differ diff --git a/docs/source/images/admin-15.png b/docs/source/images/admin-15.png new file mode 100644 index 0000000..04db89e Binary files /dev/null and b/docs/source/images/admin-15.png differ diff --git a/docs/source/images/admin-17.png b/docs/source/images/admin-17.png new file mode 100644 index 0000000..709a56d Binary files /dev/null and b/docs/source/images/admin-17.png differ diff --git a/docs/source/images/admin-2.png b/docs/source/images/admin-2.png new file mode 100644 index 0000000..7480bfb Binary files /dev/null and b/docs/source/images/admin-2.png differ diff --git a/docs/source/images/admin-3.png b/docs/source/images/admin-3.png new file mode 100644 index 0000000..c52aaf7 Binary files /dev/null and b/docs/source/images/admin-3.png differ diff --git a/docs/source/images/admin-4.png b/docs/source/images/admin-4.png new file mode 100644 index 0000000..a7d4925 Binary files /dev/null and b/docs/source/images/admin-4.png differ diff --git a/docs/source/images/admin-5.png b/docs/source/images/admin-5.png new file mode 100644 index 0000000..e3d05d2 Binary files /dev/null and b/docs/source/images/admin-5.png differ diff --git a/docs/source/images/admin-6.png b/docs/source/images/admin-6.png new file mode 100644 index 0000000..ea0d5a5 Binary files /dev/null and b/docs/source/images/admin-6.png differ diff --git a/docs/source/images/admin-7.png b/docs/source/images/admin-7.png new file mode 100644 index 0000000..9555db0 Binary files /dev/null and b/docs/source/images/admin-7.png differ diff --git a/docs/source/images/admin-8.png b/docs/source/images/admin-8.png new file mode 100644 index 0000000..5e18b35 Binary files /dev/null and b/docs/source/images/admin-8.png differ diff --git a/docs/source/images/admin-9.png b/docs/source/images/admin-9.png new file mode 100644 index 0000000..1f274f4 Binary files /dev/null and b/docs/source/images/admin-9.png differ diff --git a/docs/source/images/geosync-admin.png b/docs/source/images/geosync-admin.png new file mode 100644 index 0000000..f533f92 Binary files /dev/null and b/docs/source/images/geosync-admin.png differ diff --git a/docs/source/images/geosync-main.png b/docs/source/images/geosync-main.png new file mode 100644 index 0000000..a711f18 Binary files /dev/null and b/docs/source/images/geosync-main.png differ diff --git a/docs/source/images/geosync-service.png b/docs/source/images/geosync-service.png new file mode 100644 index 0000000..ad847ac Binary files /dev/null and b/docs/source/images/geosync-service.png differ diff --git a/docs/source/images/geosync.png b/docs/source/images/geosync.png new file mode 100644 index 0000000..ff2cd86 Binary files /dev/null and b/docs/source/images/geosync.png differ diff --git a/docs/source/images/installer.png b/docs/source/images/installer.png new file mode 100644 index 0000000..bc05028 Binary files /dev/null and b/docs/source/images/installer.png differ diff --git a/docs/source/images/project-4.png b/docs/source/images/project-4.png new file mode 100644 index 0000000..2091a53 Binary files /dev/null and b/docs/source/images/project-4.png differ diff --git a/docs/source/images/project-5.png b/docs/source/images/project-5.png new file mode 100644 index 0000000..e9e0e57 Binary files /dev/null and b/docs/source/images/project-5.png differ diff --git a/docs/source/images/services-1.png b/docs/source/images/services-1.png new file mode 100644 index 0000000..b1f3a18 Binary files /dev/null and b/docs/source/images/services-1.png differ diff --git a/docs/source/images/services-2.png b/docs/source/images/services-2.png new file mode 100644 index 0000000..b7608f6 Binary files /dev/null and b/docs/source/images/services-2.png differ diff --git a/docs/source/images/services-3.png b/docs/source/images/services-3.png new file mode 100644 index 0000000..e8c219c Binary files /dev/null and b/docs/source/images/services-3.png differ diff --git a/docs/source/index.rst b/docs/source/index.rst index 1067fd9..ac262d6 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,16 +1,11 @@ -GeoSync Docs +GeoSync =================================== -**GeoSync** is a front end application for DB-Sync and GeoDiff -It syncronizes data from QGIS and Mergin Maps Server with PostGIS databases. +**GeoSync** is a browser-based UI for Mergin Maps DB-Sync. It syncronizes data from QGIS and Mergin Maps Server with PostGIS databases. + + .. image:: images/admin-2.png -Check out the :doc:`usage` section for further information, including -how to :ref:`installation` the project. - -.. note:: - - This project is under active development. Contents -------- @@ -18,14 +13,14 @@ Contents .. toctree:: intro + install + quickstart dashboard - users + profile servers projects - groups daemons services - geoserver data frontend diff --git a/docs/source/install.rst b/docs/source/install.rst new file mode 100644 index 0000000..0f6e01d --- /dev/null +++ b/docs/source/install.rst @@ -0,0 +1,70 @@ +Install +===== + +GeoSync is installed using the included installation script. + +The script will attempt to provision an SSL certificate using Certbot. + +Ensure that your hostname is properly set. If not set the hostname using 'hostnamectl set-hostname domain.com' + +Usage +------------ + +Clone the repository:: + + git clone https://git.acugis.com/AcuGIS/GeoSync.git + +Change to the GeoSync directory:: + + cd GeoSync + +Execute the script:: + + chmod +x /installer/install.sh && ./installer/install.sh + +Upon completion, you should see the message below:: + + Backend installation is finished. + Create a PostgreSQL database and user with superuser + # create user myuser with password 'mypassword'; + # create database mydatabase with owner myuser; + # alter user myuser superuser; + Go to https://hostname/admin/setup.php to complete installation. + + +Create Database +------------ + +Create a PostgreSQL database and user. The user must be given superuser in order to create local databases:: + + root@lz370:~/domain# su - postgres + postgres@domain:~$ + + postgres@domain:~$ psql + psql (16.2 (Ubuntu 16.2-1.pgdg22.04+1)) + Type "help" for help. + + postgres=# create user myuser with password 'mypassword'; + CREATE ROLE + postgres=# create database mydatabase with owner myuser; + CREATE DATABASE + postgres=# alter user myuser superuser; + ALTER ROLE + + +Complete Setup +-------------- + +Go to https://domain.com/admin.setup.php to complete the installation. + +Once completed you can login using + +Username: admin@admin.com +Password: 1234 + + .. image:: images/geosync.png + + +Be sure to change to email and password once logged in. + + diff --git a/docs/source/intro.rst b/docs/source/intro.rst new file mode 100644 index 0000000..38e115b --- /dev/null +++ b/docs/source/intro.rst @@ -0,0 +1,13 @@ +Introduction +===== + + .. image:: images/admin-2.png + +Usage +------------ + +GeoSync provides a UI for DB-Sync and GeoDiff, allowing you to easily add Projects to be syncronized using PostGIS. + +GeoSync is built with Mergin Maps DB-Sync and GeoDiff + +It can be used with either self-hosted Mergin Maps servers or Mergin Maps Team accounts (which provides API access) diff --git a/docs/source/profile.rst b/docs/source/profile.rst new file mode 100644 index 0000000..0e430d4 --- /dev/null +++ b/docs/source/profile.rst @@ -0,0 +1,25 @@ +Profile +===== + +The Profile page allows you to edit your profile. + + +Manage Profile +---------------- + +To edit your Profile, click Profile on the left menu. + + .. image:: images/admin-13.png + +Name: The display name for the user. + +Email: The user email (used for log in) + +Password: The user password + + + + + + + diff --git a/docs/source/projects.rst b/docs/source/projects.rst new file mode 100644 index 0000000..7bec514 --- /dev/null +++ b/docs/source/projects.rst @@ -0,0 +1,59 @@ +Projects +===== + +The Project page is where you can add, edit, and delete your QGIS Projects. + +Usage +------------ + +To add a Project, click the "Add New" button at top as show below: + + + .. image:: images/admin-5.png + +For Database Type select either Local or Remote as shown below. + +Local will create a PostGIS database on the GeoSync server, which you can then access. + +Remote will prompt you for a remote PostGIS database that you wish to use. + + .. image:: images/admin-6.png + + +Populate the required fields as show below: + + .. image:: images/admin-7.png + + + + +Project: The QGIS Project name. This is case sensitive and must be the exact name of the QGIS Project. + +Workspace: The Workspace on your Mergin Server. When self-hosting this value will always be "mergin". If using Mergin Maps Team account or Enterprise Edition, this will be the actual Workspace name. + +Mergin: Select the Mergin Maps server in use from the drop-down. + +GeoPackage: This field is case sensitive and must be the exact name of the GeoPackage for the Project. Include only the name and not the extension(.gpkg) + +Password: This will serve as the PostGIS database password. + +Click the "Next" button to save the Project + + +Actions +------------ + +The Actions at right allow you to edit and delete projects, as well as show as well as dislay database connection information + +To display database connection, click on Show Connection icons as shown below: + + + .. image:: images/project-4.png + + +A modal with the information will be displayed, along with a Copy button as shown below: + + + .. image:: images/project-5.png + + diff --git a/docs/source/quickstart.rst b/docs/source/quickstart.rst new file mode 100644 index 0000000..e82813e --- /dev/null +++ b/docs/source/quickstart.rst @@ -0,0 +1,21 @@ + +Quick Start +===== + +Once logged in, click on the Administration link at top as shown below: + + .. image:: images/admin-1.png + +Short Version +------------ + +1. On the Server page, add your Mergin Maps server. + +2. On the Project page, add your project. You can have a PostGIS database created for you automatically or you can connect to an existing PostGIS database. + +3. On the Service page, start the service. + +That's it! + +There are many more configuration options and features, but the above three steps are all that is required. + diff --git a/docs/source/servers.rst b/docs/source/servers.rst index 08a8b0c..67ab2a8 100644 --- a/docs/source/servers.rst +++ b/docs/source/servers.rst @@ -1,18 +1,24 @@ Servers ===== -.. _installation: +The Servers page is where you add your Mergin Maps server(s) -Access +GeoSync supports multiple Mergin Maps servers. + +Usage ------------ -You can access the Servers page via Servers on the left menu +On the Servers page you can add, edit, and delete servers. +Click the "Add New" button at top right to add a Server. -Creating recipes ----------------- + .. image:: images/admin-3.png -Here, you can add, edit, and delete servers. +The fields to populate are below: + + .. image:: images/admin-4.png + +Name: Give your Server a name. URL: The full url of your Mergin Maps server @@ -20,4 +26,17 @@ Username: An Admin username Password: An Admin password - .. image:: images/servers.png +Click the Add icon to save the Server information + +Actions +------------ + +The Actions sections allows you to: + +1. View Admin Password + +2. Edit Server information + +3. Delete server + + diff --git a/docs/source/services.rst b/docs/source/services.rst new file mode 100644 index 0000000..c6fa247 --- /dev/null +++ b/docs/source/services.rst @@ -0,0 +1,23 @@ +Services +===== + +The Services page is where you can start, stop, and enable services as well as view log files. + +Usage +------------ + +To start or stop the service, use the Stop/Start button under Actions at right. + +To enable a Service at boot, use the toggle button as show below: + + .. image:: images/admin-8.png + +To view log files, click the Log icon under Actions at right as show below. + + + .. image:: images/services-2.png + + +You can download as well as clear the log file using the Actions at right on the log file page. + + .. image:: images/services-3.png