minor fixes, improve docs

mhils · mhils · commit b352ca6e125e · 2019-03-03T00:28:19.000+01:00
diff --git a/README.md b/README.md
@@ -107,7 +107,7 @@ It is recommended to use [r8-example](https://github.com/mhils/r8-example) as a
 and place challenges in a new separate repository. See `r8.builtin_challenges` and `r8_example` 
 for challenge examples.
 
-# Architecture
+## Architecture
 
 r8 consists of the following parts:
   1. The core **`r8` application** written in Python, which manages the currently active challenges. 
@@ -123,3 +123,11 @@ r8 consists of the following parts:
 
 To speed up development, the server can be automatically reloaded on changes using [modd](https://github.com/cortesi/modd).
 
+## Deployment
+
+For production use, it is recommended to place it behind a TLS-terminating reverse 
+proxy such as nginx. A couple of auxiliary examples are provided in the [./misc](./misc) folder:
+
+ - `crontab`: crontab example to make daily backups.
+ - `nginx.conf`: nginx configuration example for a HTTPS-only deployment.
+ - `r8.service`: systemd service file example.
diff --git a/docs/build.py b/docs/build.py
@@ -1,3 +1,5 @@
+#!/usr/bin/env python3
+
 import os
 import shutil
 
diff --git a/docs/index.html b/docs/index.html
@@ -216,7 +216,21 @@ <h3>Challenge Description Helpers<a class="headerlink" href="#challenge-descript
 <dl class="function">
 <dt id="r8.util.media">
 <code class="descclassname">r8.util.</code><code class="descname">media</code><span class="sig-paren">(</span><em>src</em>, <em>desc</em>, <em>visible: bool = True</em><span class="sig-paren">)</span><a class="headerlink" href="#r8.util.media" title="Permalink to this definition">¶</a></dt>
-<dd><p>HTML boilerplate for a bootstrap media element. Commonly used to display challenge icons.</p>
+<dd><blockquote>
+<div>HTML boilerplate for a bootstrap media element. Commonly used to display challenge icons.</div></blockquote>
+<table class="docutils field-list" frame="void" rules="none">
+<col class="field-name" />
+<col class="field-body" />
+<tbody valign="top">
+<tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple">
+<li><strong>src</strong> – Path to image.</li>
+<li><strong>desc</strong> – Media body.</li>
+<li><strong>visible</strong> – If <cite>False</cite>, a generic challenge icon will be shown instead.</li>
+</ul>
+</td>
+</tr>
+</tbody>
+</table>
 </dd></dl>
 
 <dl class="function">
@@ -269,7 +283,7 @@ <h3>TCP Server Challenge Helpers<a class="headerlink" href="#tcp-server-challeng
 <dl class="function">
 <dt id="r8.util.format_address">
 <code class="descclassname">r8.util.</code><code class="descname">format_address</code><span class="sig-paren">(</span><em>address: Tuple[str, int]</em><span class="sig-paren">)</span> &#x2192; str<a class="headerlink" href="#r8.util.format_address" title="Permalink to this definition">¶</a></dt>
-<dd><p>Format an (ip, port) address tuple.</p>
+<dd><p>Format an <cite>(ip, port)</cite> address tuple.</p>
 </dd></dl>
 
 </div>
diff --git a/misc/crontab b/misc/crontab
@@ -1,2 +1,2 @@
 # m h  dom mon dow   command
-0 * * * * cd /root && /usr/local/bin/r8 sql stmt SELECT 1 >> /var/log/r8-backup.log 2>&1
+0 0 * * * cd /root && /usr/local/bin/r8 sql stmt --backup SELECT 1 >> /var/log/r8-backup.log 2>&1
diff --git a/misc/nginx.conf b/misc/nginx.conf
diff --git a/misc/r8.service b/misc/r8.service
@@ -1,11 +1,10 @@
 [Unit]
-Description=r8 autograding system
+Description=r8 ctf system
 
 [Service]
 Type=simple
-ExecStart=/usr/local/bin/r8 run
+ExecStart=/usr/local/bin/pipenv run r8 run
 WorkingDirectory=/root/r8
-EnvironmentFile=/root/.r8_secret
 Restart=always
 
 [Install]
diff --git a/misc/status b/misc/status
diff --git a/r8/cli/sql.py b/r8/cli/sql.py
@@ -102,11 +102,7 @@ def sql_init(origin, static_dir, listen_address, database) -> None:
 @util.database_rows
 @click.argument("query", nargs=-1, required=True)
 def sql_stmt(rows, query):
-    """
-    Run a single SQL query on the database.
-    There are no safeguards in place here:
-    If you drop the table, the table is dropped.
-    """
+    """Run a single SQL query on the database."""
     util.run_sql(" ".join(query), rows=rows)
 
 
@@ -121,7 +117,6 @@ def sql_stmt(rows, query):
 def sql_file(input, debug):
     """
     Run a SQL file on the database.
-    There are no safeguards in place here: If you drop the table, the table is dropped.
     Foreign key constraints are deferred until transactions are commited, i.e. the database
     can be in an inconsistent state in between.
     """
diff --git a/r8/static/challenge.png b/r8/static/challenge.png
diff --git a/r8/static/challenge.svg b/r8/static/challenge.svg
@@ -1,9 +1,5 @@
 <svg viewBox="0 -20 128 148" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
-	<!-- 
-		https://github.com/googlei18n/noto-emoji/blob/master/svg/emoji_u1f3f0.svg + flag 
-		PNG Conversion:
-		convert -density 400 -resize x128 -background transparent challenge.svg challenge.png
-	-->
+	<!-- https://github.com/googlei18n/noto-emoji/blob/master/svg/emoji_u1f3f0.svg + flag -->
 	<path
        style="fill:#ed434b"
        d="m 64,-16 h 22 l -4.5,6.5 4.5,6.5 H 64 Z"
diff --git a/r8/util.py b/r8/util.py
@@ -50,10 +50,15 @@ def has_solved(user: str, challenge: str) -> bool:
 def media(src, desc, visible: bool = True):
     """
     HTML boilerplate for a bootstrap media element. Commonly used to display challenge icons.
+
+    Args:
+        src: Path to image.
+        desc: Media body.
+        visible: If `False`, a generic challenge icon will be shown instead.
     """
     return textwrap.dedent(f"""
         <div class="media">
-            <img class="mr-3" style="max-width: 128px; max-height: 128px;" src="{src if visible else "/challenge.png"}">
+            <img class="mr-3" style="max-width: 128px; max-height: 128px;" src="{src if visible else "/challenge.svg"}">
             <div class="align-self-center media-body">{desc}</div>
         </div>
         """)
@@ -108,13 +113,13 @@ def challenge_form_js(cid: str) -> str:
     """ % cid
 
 
-def challenge_invoke_button(cid: str, text: str) -> str:
+def challenge_invoke_button(cid: str, button_text: str) -> str:
     """
     "Trigger" button for challenges. Clicking it invokes the challenge's HTTP POST handler.
     """
     return f"""
         <form class="form-inline">
-            <button class="btn btn-primary m-1">{text}</button>
+            <button class="btn btn-primary m-1">{button_text}</button>
             <div class="response m-1"></div>
         </form>
         {challenge_form_js(cid)}
@@ -332,8 +337,8 @@ def wrapper(database, **kwds):
 
 
 def backup_db(f):
-    @click.option("--backup/--no-backup", default=True,
-                  help="Backup database to ~/.r8 before execution")
+    @click.option("--backup/--no-backup", default=True, show_default=True,
+                  help="Backup database to ~/.r8 before execution.")
     @wraps(f)
     def wrapper(backup, **kwds):
         if backup:

Original file line number	Diff line number	Diff line change
`@@ -1,3 +1,5 @@`
	`1`	`+#!/usr/bin/env python3`
	`2`	`+`
`1`	`3`	`import os`
`2`	`4`	`import shutil`
`3`	`5`
Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,2 @@`
`1`	`1`	`# m h dom mon dow command`
`2`		`-0 * * * * cd /root && /usr/local/bin/r8 sql stmt SELECT 1 >> /var/log/r8-backup.log 2>&1`
	`2`	`+0 0 * * * cd /root && /usr/local/bin/r8 sql stmt --backup SELECT 1 >> /var/log/r8-backup.log 2>&1`