Enhance onboarding for running production locally

.env.example

@@ -2,6 +2,10 @@
 # This would be set to the production domain with an env var on deployment
 DOMAIN=localhost
 
+# Username and Password for Traefik HTTP Basic Auth
+USERNAME=admin
+HASHED_PASSWORD=$apr1$7UvB4Qa3$9W8H0tmwFbQ9MYljwkbCJ. # password=changethis
+
 # Environment: local, staging, production
 ENVIRONMENT=local
 

README.md

@@ -29,11 +29,7 @@ and many many more!
 - **Multi-User Support**: Tribe offers multi-user instances, allowing for collaboration and oversight across different teams.
 - **Simple Deployment**: Implement Tribe effortlessly in your system using Docker, streamlining the setup process for various environments.
 
-## Quick Start
-
-### Configure
-
-Update configs in the `.env` files to customise your configurations.
+## How to get started
 
 Before deploying it, make sure you change at least the values for:
 
@@ -43,8 +39,6 @@ Before deploying it, make sure you change at least the values for:
 
 You can (and should) pass these as environment variables from secrets.
 
-Read the [deployment.md](./deployment.md) docs for more details.
-
 ### Generate Secret Keys
 
 Some environment variables in the `.env` file have a default value of `changethis`.
@@ -58,7 +52,15 @@ python -c "import secrets; print(secrets.token_urlsafe(32))"
 Copy the content and use that as password / secret key. And run that again to generate another secure key.
 
 
-### Creating your first team
+### Deploy Tribe locally with Docker (simplest way)
+
+[Get up and started within minutes on your local machine.](./local-deployment.md)
+
+### Deploy Tribe on a remote server
+
+[Deploy Tribe on your remote server.](./deployment.md)
+
+## Creating your first team
 
 Log into Tribe using the email and password you defined during the installation step.
 

docker-compose.local.yml

@@ -0,0 +1,48 @@
+services:
+  proxy:
+    image: traefik:v2.3
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+    ports:
+      - "80:80"
+      - "8090:8080"
+    restart: always
+    # Duplicate the command from docker-compose.yml to add --api.insecure=true
+    command:
+      # Enable Docker in Traefik, so that it reads labels from Docker services
+      - --providers.docker
+      # Add a constraint to only use services with the label for this stack
+      - --providers.docker.constraints=Label(`traefik.constraint-label`, `traefik-public`)
+      # Do not expose all Docker services, only the ones explicitly exposed
+      - --providers.docker.exposedbydefault=false
+      # Create an entrypoint "http" listening on port 80
+      - --entrypoints.http.address=:80
+      # Enable the access log, with HTTP requests
+      - --accesslog
+      # Enable the Traefik log, for configurations and errors
+      - --log
+      # Enable the Dashboard and API
+      - --api
+    labels:
+      # Enable Traefik for this service, to make it available in the public network
+      - traefik.enable=true
+      - traefik.constraint-label=traefik-public
+      # Dummy https-redirect middleware that doesn't really redirect, only to
+      # allow running it locally
+      - traefik.http.middlewares.https-redirect.contenttype.autodetect=false
+      # Define the port inside of the Docker service to use
+      - traefik.http.services.traefik-dashboard.loadbalancer.server.port=8080
+      # Make Traefik use this domain (from an environment variable) in HTTP
+      - traefik.http.routers.traefik-dashboard-http.entrypoints=http
+      - traefik.http.routers.traefik-dashboard-http.rule=Host(`traefik.localhost`)
+      # Use the special Traefik service api@internal with the web UI/Dashboard
+      - traefik.http.routers.traefik-dashboard-http.service=api@internal
+      # Using the environment variables USERNAME and HASHED_PASSWORD
+      - traefik.http.middlewares.admin-auth.basicauth.users=${USERNAME?Variable not set}:${HASHED_PASSWORD?Variable not set}
+      # Enable HTTP Basic auth, using the middleware created above
+      - traefik.http.routers.traefik-dashboard-http.middlewares=admin-auth
+
+networks:
+  traefik-public:
+    # For local dev, don't expect an external Traefik network
+    external: false

local-deployment.md

@@ -0,0 +1,86 @@
+# Running Tribe on Your Local Machine
+
+This guide will help you set up and run Tribe on your local machine as quickly as possible.
+
+## Requirements
+
+- [Docker](https://docs.docker.com/desktop/) installed on your machine. Check that docker is installed by running:
+
+  ```bash
+  docker --version
+  docker-compose --version
+  ```
+
+## Step-by-Step Setup
+
+### 1. Clone the Repository
+
+Clone the Tribe repository to your local machine and navigate to the project directory:
+```bash
+git clone https://github.com/StreetLamb/tribe.git tribe
+cd tribe
+```
+
+### 2. Set Up Environment Variables
+
+Copy the example environment variables file into a new `.env` file:
+```bash
+cp .env.example .env
+```
+
+Update the `.env` file with your custom configurations. At a minimum, you should change the following values:
+- `USERNAME`
+- `HASHED_PASSWORD` (Continue reading to learn how to generate it)
+- `SECRET_KEY`
+- `FIRST_SUPERUSER_PASSWORD`
+- `POSTGRES_PASSWORD`
+- `OPENAI_API_KEY` (Choose your preferred model provider)
+
+For variables with a default value of `changethis`, generate secure values using the following command:
+```bash
+python -c "import secrets; print(secrets.token_urlsafe(32))"
+```
+
+### 3. Creating Traefik Environment Variables
+
+Create the username for HTTP Basic Auth, e.g.:
+```bash
+export USERNAME=admin
+
+echo $USERNAME
+```
+
+To generate `HASHED_PASSWORD`, create an environment variable with the password for HTTP Basic Auth, e.g.:
+```bash
+export PASSWORD=changethis
+```
+
+Next, use openssl to generate the "hashed" version of the password for HTTP Basic Auth and store it in an environment variable:
+```bash
+export HASHED_PASSWORD=$(openssl passwd -apr1 $PASSWORD)
+
+echo $HASHED_PASSWORD
+```
+
+Copy the printed value into the `.env` file.
+
+### 4. Build and Run the Docker Containers
+
+Use Docker Compose to build the images and start the containers:
+```bash
+docker-compose -f docker-compose.yml -f docker-compose.local.yml up
+```
+
+## Accessing the Services
+
+Once the containers are running, you can access various services through the following URLs:
+
+- **Traefik UI**: [http://traefik.localhost/](http://traefik.localhost/)
+- **Frontend**: [http://localhost/](http://localhost/)
+- **Backend API Documentation**: [http://localhost/docs/](http://localhost/docs/)
+- **Backend API Base URL**: [http://localhost/api/](http://localhost/api/)
+- **Adminer**: [http://adminer.localhost/](http://adminer.localhost/)
+
+## Troubleshooting
+- **Unable to login to Traefik Dashboard**: Ensure that username and password is correct. If you are using zsh, `USERNAME` environment variable corresponds to the real user ID of the shell process, so you shold use your user ID as the username.
+- **Cannot login to Adminer**: Set 'System' to `PostgreSQL` and set the 'server' field should be `db`. The other fields should follow the values in your `.env` file.