initial readme notes

README.md

@@ -2,4 +2,57 @@
 
 resource management tooling & experiments
 
-TODO ...
+
+
+## running locally
+
+*this is a quick setup version for running
+standalone on your local machine (will be
+merged into the full docs later)*
+
+### database setup
+
+  * set the value of `sqlalchemy.url`
+    in `alembic.ini` to point to a writeable file, e.g.
+    ```python
+        sqlalchemy.url = sqlite:////absolute/path/to/foo.db
+    ```
+  * create the database by running the alembic
+    migration from the top-level directory
+    ```bash
+        alembic upgrade head
+    ```
+
+### running the app
+
+
+  * create a settings filename
+    (see `config-example.json` for an example) ... something like:
+    ```json
+      {
+        "db": "sqlite:////tmp/test.db",
+        "ssh": {
+            "username": "ro-username",
+            "private-key": "/absolute/path/to/private/key"
+        }
+      }
+    ```
+  * run the app like this
+    (`app.py` starts the server on port 44444):
+    ```bash
+        SETTINGS_FILENAME=/absolute/path/to/config.json python -m resource_management.app
+    ```
+
+### examples
+
+  * get the version
+    ```bash
+        curl http://localhost:44444/api/version
+    ```
+  * load interfaces from a router
+    ```bash
+        curl -X POST http://localhost:44444/api/initialize-router/router.host.name
+    ```
+  * view the docs by loading `http://localhost:44444/docs`
+    in your browser (there are requests for reserving
+    lags and physical lag interfaces)