Merge pull request #4351 from magfest/update-local-setup

Update Docker setup and instructions

.env.example

@@ -0,0 +1,25 @@
+# This file allows you to customize your docker compose setup to include an extra event plugin and local config files.
+# Customize the options below, then copy this file to a new file named .env inside this directory to enable them.
+# See the developers guide for full instructions on how to configure and use extra plugins!
+
+PLUGIN_NAME=yourplugin
+PLUGIN_DIR_SRC=$PWD/../${PLUGIN_NAME}/
+PLUGIN_DIR_TARGET=/app/plugins/${PLUGIN_NAME}
+
+## SINGLE-EVENT SETUP
+# Change YOURPLUGIN to your plugin name in all-caps (e.g., MAGPRIME)
+#
+UBER_CONFIG_FILES=uber.ini
+uber_plugins=["${PLUGIN_NAME}"]
+YOURPLUGIN_CONFIG_FILES=${PLUGIN_NAME}
+
+## MULTI-EVENT SETUP
+# You probably don't need this!
+# It allows you to change the plugin name above to swap between different events using the same base code.
+# Comment out the single-event setup lines above if you are using this setup.
+# 
+#UBER_CONFIG_FILES=config-${PLUGIN_NAME}.ini
+#uber_plugins=["${PLUGIN_NAME}"]
+#MAGSTOCK_CONFIG_FILES=magstock.ini
+#MAGWEST_CONFIG_FILES=magwest.ini
+#MAGPRIME_CONFIG_FILES=magprime.ini

.gitignore

@@ -33,5 +33,6 @@ uber/static/fonts/free3of9.pkl
 .history
 .lh*
 config*.ini
-sideboard.ini
+uber.ini
+.env
 .venv/

.pythonstartup.py

@@ -1,23 +1,7 @@
-import os
-import sys
-import atexit
 import readline
-import rlcompleter
 import traceback
-from pprint import pprint
-
 
 readline.parse_and_bind('tab: complete')
-history_path = os.path.expanduser('~/.pyhistory')
-
-
-@atexit.register
-def save_history():
-    readline.write_history_file(history_path)
-
-
-if os.path.exists(history_path):
-    readline.read_history_file(history_path)
 
 try:
     import cherrypy
@@ -29,16 +13,17 @@ def save_history():
     # Make it easier to do session stuff at the command line
     session = Session().session
 
-    admin = session.query(AdminAccount).filter(
-        AdminAccount.attendee_id == Attendee.id,
-        Attendee.email == '[email protected]'
-    ).order_by(AdminAccount.id).first()
+    if c.DEV_BOX:
+        admin = session.query(AdminAccount).filter(
+            AdminAccount.attendee_id == Attendee.id,
+            Attendee.email == '[email protected]'
+        ).order_by(AdminAccount.id).first()
 
     if admin:
         # Make it easier to do site section testing at the command line
         cherrypy.session = {'account_id': admin.id}
         print('Logged in as {} <{}>'.format(admin.attendee.full_name, admin.attendee.email))
-    else:
+    elif c.DEV_BOX:
         print('INFO: Could not find Test Developer admin account')
 
 except Exception as ex:

docker-compose.yml

@@ -1,7 +1,10 @@
 # docker-compose for development of ubersystem
 x-uber: &uber
   build: .
+  env_file:
+      - ./.env
   environment:
+    - PYTHONSTARTUP=/app/.pythonstartup.py
     - DB_CONNECTION_STRING=postgresql://uber_db:uber_db@db:5432/uber_db
     - uber_cherrypy_server_socket_port=80
     - uber_cherrypy_server_socket_host=0.0.0.0
@@ -14,14 +17,14 @@ x-uber: &uber
     - uber_secret_broker_url=amqp://celery:celery@rabbitmq:5672/uber
     - uber_url_root=http://localhost
     - uber_hostname=localhost
-    - uber_plugins=["magprime"]
     - uber_dev_box=True
   volumes:
-    - $PWD:/app/
-    - $PWD/../magprime:/app/plugins/magprime
+    - .:/app/
+    - ${PLUGIN_DIR_SRC:-./README.md}/:/${PLUGIN_DIR_TARGET:-/tmp/}
 
+name: ${PLUGIN_NAME:-uber}
 
-services: 
+services:
   web:
     <<: *uber
     ports:
@@ -52,11 +55,7 @@ services:
     <<: *uber
     stdin_open: true
     tty: true
-    volumes:
-      - $PWD/.pythonstartup.py:/app/.pythonstartup.py
-    environment:
-      - PYTHONSTARTUP=/app/.pythonstartup.py
-    command: ['/app/env/bin/python3']
+    command: ['python']
     profiles: ["dev"]
   flower:
     container_name: ${COMPOSE_PROJECT_NAME}-flower

docs/DEVELOPERS.md

@@ -0,0 +1,86 @@
+# Developers Guide
+## Local Installation
+The first step to writing new features or bug fixes for Ubersystem is to install a copy of the server on your local machine. This allows you to quickly see your changes in action before you [submit a pull request](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request).
+
+### Running Ubersystem with Docker Compose
+Ubersystem is composed of several different services communicating with each other. The best and easiest way to run and manage these services locally is through [Docker Compose](https://docs.docker.com/compose/). Docker Compose will create isolated containers for each service and allow them to talk with each other.
+
+The [docker-compose.yml](docker-compose.yml) file in the root of this repo will provision the core Ubersystem server with all the required services: a CherryPy web worker, a Celery task runner and scheduler, a RabbitMQ message broker, and a PostgreSQL database.
+
+Additionally, it will mount this repository directory into the containers as a volume -- each container will mount the files inside `/app/plugins/uber`. This allows code changes you make on your computer to update inside the containers without rebuilding them.
+
+### The Command Line
+Throughout this guide and elsewhere in our documentation, we will be providing commands to run in a command line terminal. If you aren't familiar with the command line, it is a text-based interface that allows you to quickly run complex operations by communicating directly with programs. Depending on your operating system, you'll likely run commands using either [Bash](https://www.gnu.org/software/bash/) (Linux), [Zsh](https://zsh.sourceforge.io/) (Mac), or [Command Prompt/CMD](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/windows-commands) (Windows).
+
+Providing command-line commands lets us give specific instructions that won't become outdated with software updates. Many applications will also have graphical interfaces that you can use as a convenience, and we encourage you to explore those when you are comfortable with the basics.
+
+### Prerequisites
+You will need the following programs installed to run Ubersystem using Docker Compose:
+
+- [Docker Desktop](https://docs.docker.com/desktop/), or [Docker Engine](https://docs.docker.com/engine/install/) if you are on Linux. This is the program that actually builds and runs the containers.
+- [Git](https://git-scm.com/), which will let you download and manage the code from this repository.
+- A code editor of your choice. If you don't already have a preference, we recommend [VSCode](https://code.visualstudio.com/) as it is free, easy to learn, and has many useful extensions. It also comes with [source control tools](https://code.visualstudio.com/docs/sourcecontrol/overview) that provide a convenient interface for using Git.
+
+### Instructions
+
+1. Clone this repository using Git by running `git clone https://github.com/magfest/ubersystem.git`. This will download the repository's code into a new folder named `ubersystem`.
+2. Enter the new folder with `cd ubersystem`.
+3. Start the server by running `docker compose up`.
+
+At this point you should see logs showing the containers downloading, compiling, and starting up. Once the line `ENGINE Bus STARTED` has printed, the server is ready and you can connect to Uber by browsing to
+[http://localhost/](http://localhost/) in your preferred browser.
+
+On first startup you can create an admin user by navigating to [http://localhost/accounts/insert_test_admin](http://localhost/accounts/insert_test_admin).
+After doing this you can log in using `[email protected]` as a username and `magfest` as a password.
+
+| :exclamation: If you didn't get a working instance check out the [troubleshooting guide](troubleshooting.md). |
+|---------------------------------------------------------------------------------------------------------------|
+
+## Adding Custom Config & Plugins
+Ubersystem uses a large array of configuration options to change the event name, event dates, t-shirt size options, and much much more. These options are defined in a configuration file.
+
+Beyond this configuration, events can write custom plugins that override templates with custom text or add new features, like badge add-ons specific to that event. If your event uses a custom plugin, you will need to download and install it as a plugin for Uber to make sure your code changes behave the way you want for your event.
+
+### Configuration
+The default configuration options, plus explanations of what each config option does, can be found in [configspeci.ini](configspec.ini).
+
+You should *only* edit configspec.ini if you are adding new config options to Uber. To set your own config, you will need to define a new configuration file that contains just the variables you want to "override" the default values on.
+
+If you're just getting started and not working for a specific event, you can use the example config overrides below. Create a new text file in the root of this repo called `uber.ini`, then copy and paste the block below and edit it to whatever values you want.
+
+```ini
+event_year = 2025
+
+[dates]
+# YYYY-MM-DD HH
+prereg_open = 2024-09-15 14
+dealer_reg_start = 2024-08-11 20
+dealer_reg_shutdown = 2024-08-11 21
+```
+
+After creating your config file, you will need to instruct Docker Compose to use it. See [loading custom config and plugins](#loading-custom-config-and-plugins) for instructions on how to do this.
+
+For more advanced information on how Ubersystem's config works, including instructions for downloading and compiling config for specific events, check out the [config guide](configuration.md).
+
+### Custom Plugins
+Ubersystem can load one or more plugins that can override many core functions and behavior. These plugins will have their own repository, and in most cases will correspond 1:1 with each event (e.g., MAGStock will use a single `magstock` plugin for its custom functionality).
+
+Custom plugins will usually be hosted on GitHub by an organization run by the event, e.g., [the plugin for Super MAGFest](https://github.com/magfest/magprime) is hosted in MAGFest's [GitHub organization](https://github.com/magfest/).
+
+You'll download the custom plugin repository the same way you download this repository, using `git clone`. One thing you'll want to make sure of is to download both repositories to the _same directory_, rather than downloading the custom plugin inside the `ubersystem` directory. If you still have the terminal open from the installation instructions above, you can use `Ctrl-` or `Cmd-C` to exit Docker Compose and run `cd ../` to quickly travel "up" a directory before running `git clone`.
+
+When cloning the repository with Git (`git clone REPOURL`), your repo URL can look like either `https://github.com/magfest/magprime` (copied from your browser URL bar) or `https://github.com/magfest/magprime.git` (copied from the "Code" dropdown on GitHub).
+
+To enable your plugin, you'll follow the loading instructions below. First, though, make sure your plugin has a config override file. You can [download the file from a config repo](configuration#generated-configuration) (if applicable) or create a blank text file in the root folder of the plugin. It should be named after the plugin itself, e.g., `/magprime/magprime.ini`.
+
+### Loading Custom Config and Plugins
+The last step for loading custom config or plugins (or both) is to tell Docker Compose to use them. There are a few ways to do this, but here we'll cover how to use environment variables defined in an `.env` file.
+
+You may notice that no `.env` file exists in this repository -- this is intended. Both config files and the .env file do not get uploaded (or "checked into") Git. This allows you to set up your config and plugins without affecting anyone else's setup.
+
+Instead, we have an `.env.example` file, located in the root of this repository. Copy this file and paste it as a new file in the same directory, then rename the new file to `.env`. In this file, you'll have two lines to edit:
+
+- On the line `PLUGIN_NAME=yourplugin`, replace `yourplugin` with your plugin folder's name in its normal case, e.g., `magprime`.
+- On the line `YOURPLUGIN_CONFIG_FILES=${PLUGIN_NAME}`, change `YOURPLUGIN` to an all-caps version of your plugin folder's name, e.g., `MAGPRIME`.
+
+If you used these instructions to set up your config file(s) (`uber.ini` for this repository, plus `yourplugin.ini` for any custom plugins), that's all you need to change. The next time you use `docker compose up`, your plugin and custom config will be loaded!