From 38a73b2b3126b28ba782f9e85c3919ebc65e9bf3 Mon Sep 17 00:00:00 2001 From: brian Date: Thu, 18 Jul 2024 12:45:03 -0400 Subject: [PATCH 01/10] Retitle and clarify setup sections --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 385718da..cfb79d2f 100644 --- a/README.md +++ b/README.md @@ -73,12 +73,13 @@ site (served as static files). [django42]: https://docs.djangoproject.com/en/4.2/ -## Setting up the Project +## Setup and Usage +Once this project's required dependencies are enabled on your system, you will +be able to run the legal-tools application and generate static files. -### Data Repository -Visit [Cloning a Repository][gitclone] on how to clone a GitHub repository. +### Prerequisites The [creativecommons/cc-legal-tools-data][repodata] project repository should be cloned into a directory adjacent to this one: From b75540b125b6bcad2dba8e60a8ff9d55c8e24f62 Mon Sep 17 00:00:00 2001 From: brian Date: Thu, 18 Jul 2024 12:53:26 -0400 Subject: [PATCH 02/10] Flesh out prerequisites and distinguish install --- README.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 52 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index cfb79d2f..265fdcc1 100644 --- a/README.md +++ b/README.md @@ -81,8 +81,58 @@ be able to run the legal-tools application and generate static files. ### Prerequisites -The [creativecommons/cc-legal-tools-data][repodata] project repository should -be cloned into a directory adjacent to this one: +This project depends on Docker and Git. + + +#### MacOS + +Mac users can install Git using [these instructions][macos-git]. + +Docker Desktop can be installed using [these instructions][macos-docker]. + +[macos-git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git#_installing_on_macos +[macos-docker]: https://docs.docker.com/desktop/install/mac-install + + +#### Linux + +Git is optimally installed using your distribution's package manager. +See [these commands][linux-git] for a wide range of popular distros. + +Both Docker Desktop and Docker Engine are separately supported on Linux. +Both include the required Compose command plugin, but Docker Engine is +typically much easier to install. + +The [Docker CE resource][linux-docker-engine] links to installation +instructions for Docker Engine and Compose for various Linux distributions. +[Linux Docker Desktop][linux-docker-desktop] links to instructions for the +graphical desktop app that includes the commandline interface and Compose. + +[linux-git]: https://git-scm.com/download/linux +[linux-docker-engine]: https://docs.docker.com/engine/install +[linux-docker-desktop]: https://docs.docker.com/desktop/install/linux-install + + +#### Windows + +You must use Windows 10 or 11 with [Windows Subsystem for Linux (WSL2)][wsl2]. + +Git should be installed within WSL2, using the appropriate Linux installation +method. For WSL2 Ubuntu, the command is `sudo apt-get install git`. + +Docker Desktop should be installed on Windows itself and integrated with WSL2 as +explained in [these instructions][docker-wsl2]. Unlike Git, you should not +install Docker within your WSL2 environment. + +[wsl2]: https://docs.microsoft.com/en-us/windows/wsl/install +[docker-wsl2]: https://docs.docker.com/desktop/windows/wsl + + +### Codebases Setup + +Both this repository and the [creativecommons/cc-legal-tools-data][repodata] +project repository should be cloned side by side, resulting in a structure like +the following: ``` PARENT_DIR ├── cc-legal-tools-app (git clone of this repository) From d83e6a88ca652d0ac685411d922dc2d49d4e3b56 Mon Sep 17 00:00:00 2001 From: brian Date: Thu, 18 Jul 2024 12:54:44 -0400 Subject: [PATCH 03/10] Adjust 2-repo structure model --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 265fdcc1..ff3bf1b1 100644 --- a/README.md +++ b/README.md @@ -134,9 +134,9 @@ Both this repository and the [creativecommons/cc-legal-tools-data][repodata] project repository should be cloned side by side, resulting in a structure like the following: ``` -PARENT_DIR -├── cc-legal-tools-app (git clone of this repository) -└── cc-legal-tools-data (git clone of the cc-legal-tools-data repository) +creative-commons/ +├── cc-legal-tools-app/ (git clone of this repository) +└── cc-legal-tools-data/ (git clone of the cc-legal-tools-data repository) ``` If it is not cloned into the default location, the Django From 69ab0b16b7bf2e00e537fc8449172a0530731466 Mon Sep 17 00:00:00 2001 From: brian Date: Thu, 18 Jul 2024 12:56:38 -0400 Subject: [PATCH 04/10] Remove Django/env instruction for unconventional repo placement --- README.md | 4 ---- 1 file changed, 4 deletions(-) diff --git a/README.md b/README.md index ff3bf1b1..5607908c 100644 --- a/README.md +++ b/README.md @@ -139,10 +139,6 @@ creative-commons/ └── cc-legal-tools-data/ (git clone of the cc-legal-tools-data repository) ``` -If it is not cloned into the default location, the Django -`DATA_REPOSITORY_DIR` Django configuration setting, or the -`DATA_REPOSITORY_DIR` environment variable can be used to configure its -location. [gitclone]:https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository [repodata]:https://github.com/creativecommons/cc-legal-tools-data From 8277505d85a39ad91206b9db95de103599eb48cc Mon Sep 17 00:00:00 2001 From: brian Date: Thu, 18 Jul 2024 12:58:11 -0400 Subject: [PATCH 05/10] Re-title and flesh out setup and run instructions --- README.md | 64 ++++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 44 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 5607908c..35a2ce6b 100644 --- a/README.md +++ b/README.md @@ -139,30 +139,52 @@ creative-commons/ └── cc-legal-tools-data/ (git clone of the cc-legal-tools-data repository) ``` +To achieve this, we recommend the following procedure: + +1. Create and change to a container directory, such as `creative-commons` or `cc`. + ```shell + mkdir creative-commons + cd creative-commons + ``` +2. Clone both repos using SSH or, if that does not work, HTTPS protocol. + ```shell + git clone git@github.com:creativecommons/cc-legal-tools-app.git + git clone git@github.com:creativecommons/cc-legal-tools-data.git + ``` + or + ```shell + git clone https://github.com/creativecommons/cc-legal-tools-app.git + git clone https://github.com/creativecommons/cc-legal-tools-data.git + ``` + +Visit [Cloning a Repository][gitclone] for more on how to clone a GitHub +repository. [gitclone]:https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository -[repodata]:https://github.com/creativecommons/cc-legal-tools-data -### Docker Compose Setup +### Docker Prep and Execution -Use the following instructions to start the project with Docker compose. -Pleaes note that CC staff use macOS for development--please help us with -documenting other operating systems if you encounter issues. +Use the following instructions to prepare and run the project with Docker +Compose. -1. Ensure the [Data Repository](#data-repository), above, is in place -2. [Install Docker Engine](https://docs.docker.com/engine/install/) -3. Ensure you are at the top level of the directory where you cloned this repository (where `manage.py` is) -4. Create Django local settings file +1. Ensure all prerequisites and repositories are in place. +2. Ensure you are at the top level of the directory where you cloned this +repository (where `manage.py` is). + ```shell + cd cc-legal-tools-app + ``` +3. Create Django local settings file from the example file. ```shell cp cc_legal_tools/settings/local.example.py cc_legal_tools/settings/local.py ``` - - Update variables in new file, as necessary -5. Build the containers + - Update variables in new file, if necessary. + - This file is ignored by Git. +4. Build the containers. ```shell docker compose build ``` -6. **Run the containers** +5. **Run the containers.** ```shell docker compose up ``` @@ -172,17 +194,19 @@ documenting other operating systems if you encounter issues. transparently as long as the development server is running. 2. **static** ([127.0.0.1:8006](http://127.0.0.1:8006/)): a static web server serving [creativecommons/cc-legal-tools-data][repodata]:`docs/` -7. Initialize data +6. Initialize data. +Open a separate terminal tab, and in the same directory, run: ```shell ./dev/init_data.sh ``` - 1. Delete database (which may not yet exist) - 2. Initialize database - 3. Perform databsea migrations - 4. Crate supseruser (will prompt for password) - 5. Load data - -[repodata]:https://github.com/creativecommons/cc-legal-tools-data + a. Deletes database (which may not yet exist) + b. Initializes database + c. Performs database migrations + d. Creates supseruser (will prompt for password) + e. Loads data + +Note: Once this full setup is performed, running Step 5 above will execute the +application on any subsequent occasion. ### Manual Setup From 1530eb10793554fe13d6e25f8e537aa3ba36bedd Mon Sep 17 00:00:00 2001 From: brian Date: Thu, 18 Jul 2024 13:02:25 -0400 Subject: [PATCH 06/10] Remove extra spaces from line endings --- README.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 35a2ce6b..68529a87 100644 --- a/README.md +++ b/README.md @@ -103,9 +103,9 @@ Both Docker Desktop and Docker Engine are separately supported on Linux. Both include the required Compose command plugin, but Docker Engine is typically much easier to install. -The [Docker CE resource][linux-docker-engine] links to installation +The [Docker CE resource][linux-docker-engine] links to installation instructions for Docker Engine and Compose for various Linux distributions. -[Linux Docker Desktop][linux-docker-desktop] links to instructions for the +[Linux Docker Desktop][linux-docker-desktop] links to instructions for the graphical desktop app that includes the commandline interface and Compose. [linux-git]: https://git-scm.com/download/linux @@ -117,11 +117,11 @@ graphical desktop app that includes the commandline interface and Compose. You must use Windows 10 or 11 with [Windows Subsystem for Linux (WSL2)][wsl2]. -Git should be installed within WSL2, using the appropriate Linux installation +Git should be installed within WSL2, using the appropriate Linux installation method. For WSL2 Ubuntu, the command is `sudo apt-get install git`. -Docker Desktop should be installed on Windows itself and integrated with WSL2 as -explained in [these instructions][docker-wsl2]. Unlike Git, you should not +Docker Desktop should be installed on Windows itself and integrated with WSL2 as +explained in [these instructions][docker-wsl2]. Unlike Git, you should not install Docker within your WSL2 environment. [wsl2]: https://docs.microsoft.com/en-us/windows/wsl/install @@ -130,8 +130,8 @@ install Docker within your WSL2 environment. ### Codebases Setup -Both this repository and the [creativecommons/cc-legal-tools-data][repodata] -project repository should be cloned side by side, resulting in a structure like +Both this repository and the [creativecommons/cc-legal-tools-data][repodata] +project repository should be cloned side by side, resulting in a structure like the following: ``` creative-commons/ @@ -157,7 +157,7 @@ To achieve this, we recommend the following procedure: git clone https://github.com/creativecommons/cc-legal-tools-data.git ``` -Visit [Cloning a Repository][gitclone] for more on how to clone a GitHub +Visit [Cloning a Repository][gitclone] for more on how to clone a GitHub repository. [gitclone]:https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository @@ -165,11 +165,11 @@ repository. ### Docker Prep and Execution -Use the following instructions to prepare and run the project with Docker +Use the following instructions to prepare and run the project with Docker Compose. 1. Ensure all prerequisites and repositories are in place. -2. Ensure you are at the top level of the directory where you cloned this +2. Ensure you are at the top level of the directory where you cloned this repository (where `manage.py` is). ```shell cd cc-legal-tools-app @@ -205,7 +205,7 @@ Open a separate terminal tab, and in the same directory, run: d. Creates supseruser (will prompt for password) e. Loads data -Note: Once this full setup is performed, running Step 5 above will execute the +Note: Once this full setup is performed, running Step 5 above will execute the application on any subsequent occasion. From f28222b680a575e436f73e6f68b491f533044781 Mon Sep 17 00:00:00 2001 From: brian Date: Thu, 18 Jul 2024 13:14:07 -0400 Subject: [PATCH 07/10] Revert to former sub-steps listing for init-data.sh --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 68529a87..7ef0aef2 100644 --- a/README.md +++ b/README.md @@ -199,11 +199,11 @@ Open a separate terminal tab, and in the same directory, run: ```shell ./dev/init_data.sh ``` - a. Deletes database (which may not yet exist) - b. Initializes database - c. Performs database migrations - d. Creates supseruser (will prompt for password) - e. Loads data + 1. Deletes database (which may not yet exist) + 2. Initializes database + 3. Performs database migrations + 4. Creates supseruser (will prompt for password) + 5. Loads data Note: Once this full setup is performed, running Step 5 above will execute the application on any subsequent occasion. From 6acf3630de0c33a149c6ca9c85beb87932e4513a Mon Sep 17 00:00:00 2001 From: Timid Robot Zehta Date: Thu, 18 Jul 2024 10:49:12 -0700 Subject: [PATCH 08/10] include codebases in prerequisites preamble --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 7ef0aef2..665fadba 100644 --- a/README.md +++ b/README.md @@ -81,7 +81,8 @@ be able to run the legal-tools application and generate static files. ### Prerequisites -This project depends on Docker and Git. +This project depends on Docker and Git. It also requires this repository and +the data repository (the codebases) be cloned next to each other. #### MacOS From 2f6bac4d6a805d4b5af796dafa05b614be1b092f Mon Sep 17 00:00:00 2001 From: Timid Robot Zehta Date: Thu, 18 Jul 2024 14:20:32 -0700 Subject: [PATCH 09/10] update to use page titles for links and minor formatting changes --- README.md | 37 +++++++++++++++++++++---------------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 665fadba..88d9a6dc 100644 --- a/README.md +++ b/README.md @@ -87,9 +87,11 @@ the data repository (the codebases) be cloned next to each other. #### MacOS -Mac users can install Git using [these instructions][macos-git]. +Mac users can install Git using these instructions: [Git - Installing Git - +Installing on macOS][macos-git]. -Docker Desktop can be installed using [these instructions][macos-docker]. +Docker Desktop can be installed using these instructions: [Install Docker +Desktop on Mac | Docker Docs][macos-docker]. [macos-git]: https://git-scm.com/book/en/v2/Getting-Started-Installing-Git#_installing_on_macos [macos-docker]: https://docs.docker.com/desktop/install/mac-install @@ -97,17 +99,18 @@ Docker Desktop can be installed using [these instructions][macos-docker]. #### Linux -Git is optimally installed using your distribution's package manager. -See [these commands][linux-git] for a wide range of popular distros. +Git is optimally installed using your distribution's package manager. See [Git +- Download for Linux and Unix][linux-git] for a wide range of popular distros. Both Docker Desktop and Docker Engine are separately supported on Linux. Both include the required Compose command plugin, but Docker Engine is -typically much easier to install. - -The [Docker CE resource][linux-docker-engine] links to installation -instructions for Docker Engine and Compose for various Linux distributions. -[Linux Docker Desktop][linux-docker-desktop] links to instructions for the -graphical desktop app that includes the commandline interface and Compose. +typically much easier to install: +- _Recommended:_ See [Install Docker Engine | Docker Docs][linux-docker-engine] + for links to installation instructions for Docker Engine and Compose for + various Linux distributions. +- See [Install Docker Desktop on Linux | Docker + Docs][linux-docker-desktop] for links to instructions for the graphical + desktop app that includes the commandline interface and Compose [linux-git]: https://git-scm.com/download/linux [linux-docker-engine]: https://docs.docker.com/engine/install @@ -116,14 +119,16 @@ graphical desktop app that includes the commandline interface and Compose. #### Windows -You must use Windows 10 or 11 with [Windows Subsystem for Linux (WSL2)][wsl2]. +You must use Windows 10 or 11 with Windows Subsystem for Linux (WSL2). For +installation instructions: see [Install WSL | Microsoft Learn][wsl2]. Git should be installed within WSL2, using the appropriate Linux installation method. For WSL2 Ubuntu, the command is `sudo apt-get install git`. -Docker Desktop should be installed on Windows itself and integrated with WSL2 as -explained in [these instructions][docker-wsl2]. Unlike Git, you should not -install Docker within your WSL2 environment. +Docker Desktop should be installed on Windows itself and integrated with WSL2 +as explained in [Docker Desktop WSL 2 backend on Windows | Docker +Docs][docker-wsl2]. Unlike Git, you should not install Docker within your WSL2 +environment. [wsl2]: https://docs.microsoft.com/en-us/windows/wsl/install [docker-wsl2]: https://docs.docker.com/desktop/windows/wsl @@ -158,8 +163,8 @@ To achieve this, we recommend the following procedure: git clone https://github.com/creativecommons/cc-legal-tools-data.git ``` -Visit [Cloning a Repository][gitclone] for more on how to clone a GitHub -repository. +Visit [Cloning a repository - GitHub Docs][gitclone] for more on how to clone a +GitHub repository. [gitclone]:https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository From b835d9bd716279dc782ea5e2dca13488d71ad5c8 Mon Sep 17 00:00:00 2001 From: Timid Robot Zehta Date: Thu, 18 Jul 2024 14:21:46 -0700 Subject: [PATCH 10/10] correct formatting issue that i introduced --- README.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 88d9a6dc..bd506f5b 100644 --- a/README.md +++ b/README.md @@ -99,8 +99,9 @@ Desktop on Mac | Docker Docs][macos-docker]. #### Linux -Git is optimally installed using your distribution's package manager. See [Git -- Download for Linux and Unix][linux-git] for a wide range of popular distros. +Git is optimally installed using your distribution's package manager. See +[Git- Download for Linux and Unix][linux-git] for a wide range of popular +distros. Both Docker Desktop and Docker Engine are separately supported on Linux. Both include the required Compose command plugin, but Docker Engine is