-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Changed name of repository from `uccser-development-proxy` to `uccser-development-stack` to better reflect the contents and purpose of these tools. - Renamed the Docker network to match the new repository name. - Update to Docker Compose v2 commands. - Add instructions for running within a WSL2 environment.
- Loading branch information
1 parent
f29875c
commit 02674d1
Showing
1 changed file
with
64 additions
and
27 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,51 +1,88 @@ | ||
| # UCCSER Development Proxy | ||
| # UCCSER Development Stack | ||
|
|
||
| This proxy is required when working on the following UCCSER websites: | ||
| *Version 3.0* | ||
|
|
||
| This stack is required when working on the following UCCSER projects: | ||
|
|
||
| - [CS Unplugged](https://github.com/uccser/cs-unplugged) | ||
| - [CS Unplugged Classic](https://github.com/uccser/cs-unplugged-classic) | ||
| - [CS Field Guide](https://github.com/uccser/cs-field-guide) | ||
| - [codeWOF](https://github.com/uccser/codewof) | ||
| - [DTHM for Kaiako](https://github.com/uccser/dthm4kaiako) | ||
|
|
||
| This proxy allows multiple systems to run on your development environment simultaneously under HTTPS. | ||
| The proxy also includes a system for catching emails sent by these systems. | ||
| A proxy is used to mimic our production environment on your local machine, for consistency when developing. | ||
| This proxy also allows multiple of our projects to run on your development environment simultaneously. | ||
|
|
||
| The stack also includes a tool for catching emails sent by our UCCSER projects. | ||
|
|
||
| # Installation | ||
|
|
||
| These steps are suitable for installing within the recommended Linux environment, either straight Linux or Linux within a WSL2 distro, as defined in our [UCCSER development guide](https://github.com/uccser/uccser-development-guide). | ||
| If you have used this development guide, the first two steps of these installation steps are already completed. | ||
|
|
||
| # Setup | ||
| 1. Install [Docker](https://docs.docker.com/engine/). | ||
| 2. Install [Docker Compose](https://docs.docker.com/compose/install/compose-plugin/) (the v2 plugin, not the older v1 `docker-compose`). | ||
| 3. Install [mkcert](https://github.com/FiloSottile/mkcert). | ||
| 4. Run `mkcert -install` to install the certificate authority. | ||
| 5. Run `./create-certs.sh` to create the required certificates. | ||
|
|
||
| You will need to have the following tools installed to run this proxy: | ||
| The `create-certs.sh` script will create SSL certificates for our UCCSER projects. | ||
| The script will also tell you when the certificates expire, when you will be required to rerun this setup to regenerate the certificates. | ||
|
|
||
| - Docker | ||
| - Docker Compose | ||
| - [mkcert](https://github.com/FiloSottile/mkcert) | ||
| If you are using WSL2 to run Docker on Windows, there are a few extra steps to get the stack installed correctly: | ||
|
|
||
| Once these tools have been installed, then run `./create-certs.sh`. | ||
| The script will create SSL certificates for all our websites. | ||
| The script will finish with telling you when the certificates expire, where you will be required to rerun this setup. | ||
| 6. Install [mkcert](https://github.com/FiloSottile/mkcert) on the Windows host machine. | ||
| 7. Open a Windows Powershell terminal and run `mkcert -install` to install the certificate authority on Windows. | ||
| 8. Run `mkcert -CAROOT` to find the location of the CA files in Windows. | ||
| 9. Open this location in Windows Explorer and copy the two files within the directory. | ||
| 10. Open a terminal within the Linux environment and run `mkcert -CAROOT` to find the location of the CA files in Linux. | ||
| 11. Open this location in Windows Explorer and paste the two Windows files into this location, replacing the existing files. | ||
| - The Linux disk drives can be found with <kbd>Win</kbd> + <kbd>R</kbd> (opens the Run prompt) and entering `\\wsl$` | ||
| 12. Open a terminal within the Linux environment and run `./create-certs.sh` to recreate the required certificates. | ||
|
|
||
| # Usage | ||
|
|
||
| To run the proxy, run `docker-compose up -d` in this project directory. | ||
| Docker will run the proxy in the background. | ||
| To run the development stack, run `docker compose up -d` in this project directory. | ||
| Docker will run the stack in the background. | ||
|
|
||
| > **Tip:** Add an alias to the end of your `.bashrc` file that allows starting the proxy from anywhere. | ||
| > For example (you will need to modify the path to the docker compose file for your specific system): | ||
| > ``` | ||
| > alias uc-dev="docker-compose -f ~/Projects/uccser-development-proxy/docker-compose.yml up -d" | ||
| > ``` | ||
| Once the development stack is running, the following features are available: | ||
|
|
||
| You can view the dashboard of the proxy by opening a browser and going to `proxy.localhost` in your preferred web browser. | ||
| - **Proxy dashboard:** Open https://proxy.localhost. | ||
| - **Email system:** Open https://email.localhost. | ||
|
|
||
| You can view the email system by opening a browser and going to `email.localhost` in your preferred web browser. | ||
| > We recommend adding an alias to your terminal to start the development stack from anywhere. | ||
| > The following command will add the alias `uc-dev` to the Bash terminal configuration file `.bashrc`. | ||
| > You will need to modify the path to the docker compose file for your specific system. | ||
| > | ||
| > ``` | ||
| > `echo 'alias uc-dev="docker compose -f ~/uccser-development-stack/docker-compose.yml up -d"' >> ~/.bashrc` | ||
| > ``` | ||
| To view logs of the proxy, run `docker-compose logs -f traefik`. | ||
| To view logs of the proxy, run `docker compose logs -f traefik`. | ||
|
|
||
| Do shutdown the proxy, run `docker-compose down`. | ||
| If you get a error when running this command, saying `ERROR: error while removing network: network uccser-development-proxy`, then one of our website systems is likely still running. | ||
| The proxy will be shutdown, but the network will remain active. | ||
| If you wish to remove the network, you will need to end all UCCSER website systems first. | ||
| To shutdown the development stack, run `docker compose down`. | ||
| If you get a error when running this command, saying `ERROR: error while removing network: network uccser-development-stack`, then one of our website systems is likely still running. | ||
| The stack will be shutdown, but the network will remain active. | ||
| If you wish to remove the network, you will need to end all UCCSER website systems first then rerun the shutdown command. | ||
|
|
||
| # Notes | ||
|
|
||
| The proxy binds to ports 80 and 443. | ||
| If you are trying to run other systems that wish to bind to these ports, you will need to shutdown the proxy. | ||
| If you are trying to run other systems that wish to bind to these ports, you will need to shutdown the stack. | ||
|
|
||
| # Changelog | ||
|
|
||
| ## 3.0 | ||
|
|
||
| - Changed name of repository from `uccser-development-proxy` to `uccser-development-stack` to better reflect the contents and purpose of these tools. | ||
| - Renamed the Docker network to match the new repository name. | ||
| - Update to Docker Compose v2 commands. | ||
| - Add instructions for running within a WSL2 environment. | ||
|
|
||
| ## 2.0 | ||
|
|
||
| - Add Mailhog for email capturing during local development. | ||
|
|
||
| ## 1.0 | ||
|
|
||
| - Initial release of Traefik proxy with HTTPS certificate generation. |