Merge branch 'dev' into plugins-browsertrix

README.md

@@ -417,32 +417,117 @@ For more discussion on managed and paid hosting options see here: <a href="https
 
 #### ⚡️&nbsp; CLI Usage
 
-```bash
-# archivebox [subcommand] [--args]
-# docker-compose run archivebox [subcommand] [--args]
-# docker run -v $PWD:/data -it [subcommand] [--args]
+ArchiveBox commands can be run in a terminal directly on your host, or via Docker/Docker Compose depending on how you installed it above.
 
-archivebox init --setup      # safe to run init multiple times (also how you update versions)
-archivebox --version
-archivebox help
+```bash
+mkdir -p ~/archivebox/data   # create a new data dir anywhere
+cd ~/archivebox/data         # IMPORTANT: cd into the directory
+
+# archivebox [subcommand] [--args]
 ```
 
+> [!TIP]
+> Whether in Docker or not, ArchiveBox commands all work the same way, and can be used in tandem to access the same data directory.
+> For example, you can run the Web UI in Docker Compose, and run one-off commands on host with `pip`-installed ArchiveBox or in Docker interchangeably.
+
+<details>
+<summary><i>Expand to show examples...</i></summary><br/>
+
+<pre lang="bash"><code style="white-space: pre-line">
+docker compose up -d                                      # start the Web UI server in the background
+docker compose run archivebox add 'https://example.com'   # add a test URL to snapshot w/ Docker Compose
+
+archivebox list 'https://example.com'                     # fetch it with pip-installed archivebox on the host
+docker compose run archivebox list 'https://example.com'                       # or w/ Docker Compose
+docker run -it -v $PWD:/data archivebox/archivebox list 'https://example.com'  # or w/ Docker, all equivalent
+</code></pre>
+
+</details>
+<br/>
+
+##### Bare Metal Usage (`pip`/`apt`/`brew`/etc.)
+
+<br/>
+<details open>
+<summary><i>Click to expand...</i></summary>
+<br/>
+
+<pre lang="bash"><code style="white-space: pre-line">
+archivebox init --setup      # safe to run init multiple times (also how you update versions)
+archivebox version           # get archivebox version info and more
+archivebox add --depth=1 'https://news.ycombinator.com'
+</code></pre>
+
+</details>
+<br/>
+
+##### Docker Compose Usage
+
+<br/>
+<details>
+<summary><i>Click to expand...</i></summary>
+<br/>
+
+<pre lang="bash"><code style="white-space: pre-line">
+# make sure you have `docker-compose.yml` from the Quickstart instructions first
+docker compose run archivebox init --setup
+docker compose run archivebox version
+docker compose run archivebox add --depth=1 'https://news.ycombinator.com'
+</code></pre>
+
+</details>
+<br/>
+
+##### Docker Usage
+
+<br/>
+<details>
+<summary><i>Click to expand...</i></summary>
+<br/>
+
+<pre lang="bash"><code style="white-space: pre-line">
+docker run -v $PWD:/data -it archivebox/archivebox init --setup
+docker run -v $PWD:/data -it archivebox/archivebox version
+</code></pre>
+
+</details>
+<br/>
+
+#### Next Steps
+
+- `archivebox help/version` to see the list of available subcommands and currently installed version info
 - `archivebox setup/init/config/status/manage` to administer your collection
 - `archivebox add/schedule/remove/update/list/shell/oneshot` to manage Snapshots in the archive
 - `archivebox schedule` to pull in fresh URLs regularly from [bookmarks/history/Pocket/Pinboard/RSS/etc.](#input-formats)
 
+
 #### 🖥&nbsp; Web UI Usage
 
+##### Start the Web Server
 ```bash
-archivebox manage createsuperuser  # create admin user via CLI (or use ADMIN_PASSWORD env variable)
+# Bare metal (pip/apt/brew/etc):
 archivebox server 0.0.0.0:8000     # open http://127.0.0.1:8000 to view it
 
-# you can also configure whether or not login is required for most features
-archivebox config --set PUBLIC_INDEX=False
-archivebox config --set PUBLIC_SNAPSHOTS=False
-archivebox config --set PUBLIC_ADD_VIEW=False
+# Docker Compose:
+docker compose up
+
+# Docker:
+docker run -v $PWD:/data -it -p 8000:8000 archivebox/archivebox
 ```
 
+##### Allow Public Access or Create an Admin User
+```bash
+archivebox manage createsuperuser              # create a new admin username & pass
+# OR                                           # OR
+archivebox config --set PUBLIC_ADD_VIEW=True   # allow guests to submit URLs
+archivebox config --set PUBLIC_SNAPSHOTS=True  # allow guests to see snapshot content
+archivebox config --set PUBLIC_INDEX=True      # allow guests to see list of all snapshots
+
+# restart the server to apply any config changes
+```
+
+*Docker hint:* Set the [`ADMIN_USERNAME` & `ADMIN_PASSWORD`)](https://github.com/ArchiveBox/ArchiveBox/wiki/Configuration#admin_username--admin_password) env variables to auto-create an admin user on first-run.
+
 #### 🗄&nbsp; SQL/Python/Filesystem Usage
 
 ```bash

archivebox/config.py

@@ -112,6 +112,7 @@ CONFIG_SCHEMA: Dict[str, ConfigDefaultDict] = {
         'LDAP_FIRSTNAME_ATTR':       {'type': str,   'default': None},
         'LDAP_LASTNAME_ATTR':        {'type': str,   'default': None},
         'LDAP_EMAIL_ATTR':           {'type': str,   'default': None},
+        'LDAP_CREATE_SUPERUSER':      {'type': bool,  'default': False},
     },
 
     'ARCHIVE_METHOD_TOGGLES': {

archivebox/core/apps.py

@@ -8,3 +8,8 @@ class CoreAppConfig(AppConfig):
 
     # WIP: broken by Django 3.1.2 -> 4.0 migration
     default_auto_field = 'django.db.models.UUIDField'
+
+    def ready(self):
+        from .auth import register_signals
+
+        register_signals()

archivebox/core/auth.py

@@ -0,0 +1,13 @@
+import os
+from django.conf import settings
+from ..config import (
+    LDAP
+)
+
+def register_signals():
+
+    if LDAP:
+        import django_auth_ldap.backend
+        from .auth_ldap import create_user
+
+        django_auth_ldap.backend.populate_user.connect(create_user)

archivebox/core/auth_ldap.py

@@ -0,0 +1,12 @@
+from django.conf import settings
+from ..config import (
+    LDAP_CREATE_SUPERUSER
+)
+
+def create_user(sender, user=None, ldap_user=None, **kwargs):
+
+    if not user.id and LDAP_CREATE_SUPERUSER:
+        user.is_superuser = True
+
+    user.is_staff = True
+    print(f'[!] WARNING: Creating new user {user} based on LDAP user {ldap_user} (is_staff={user.is_staff}, is_superuser={user.is_superuser})')