deployment instructions

docs/DEPLOYMENT.md

@@ -0,0 +1,145 @@
+# Deployment instructions:
+
+There are three ways to deploy mCaptcha:
+
+1. Docker
+2. Docker compose
+3. Bare metal
+
+## Docker
+
+NOTE: We'll publish pre-built images once we reach `alpha`.
+
+1. Build image:
+
+```bash
+$ cd guard && docker build -t mcaptcha/guard:latest .
+```
+
+2. Set configuration in [configuration file](../config/default.toml)
+
+3. Run image:
+
+If you have already have a Postgres instance running, then:
+
+```bash
+docker run -p <host-machine-port>:<port-in-configuration-file> \
+	--add-host=database:<database-ip-addrss> \
+	-e RUST_LOG=debug \
+	-e DATABASE_URL="postgres://<db-user>:<db-password>@database:<db-port>/<db-name>" \
+	mcaptcha/guard:latest
+```
+
+If you don't have a Postgres instance running, you can either install
+one using a package manager or launch one with docker. A [docker-compose
+configuration]('../docker-compose.yml) is available that will launch both
+a database instance guard instance.
+
+## With docker-compose
+
+1. Follow steps above to build docker image.
+
+2. Set database password [docker-compose configuration]('../docker-compose.yml).
+
+3. Launch network:
+
+```bash
+$ docker-compose up -d
+```
+
+## Bare metal:
+
+The process is tedious, most of this will be automated with a script in
+the future.
+
+### 1. Install postgres if you don't have it already.
+
+### 2. Create new user for running `guard`:
+
+```bash
+$ sudo useradd -b /srv -m -s /usr/bin/zsh mcaptcha
+```
+
+### 3. Create new user in Postgres
+
+```bash
+$ sudo -iu postgres # switch to `postgres` user
+$ psql
+postgres=#  CREATE USER mcaptcha WITH PASSWORD 'my super long password and yes you need single quote`;
+$  createdb -O mcaptcha mcaptcha # create db 'mcaptcha' with 'mcaptcha' as owner
+```
+
+### 4. Build `guard`:
+
+To build `guard`, you need the following dependencies:
+
+1. rust
+2. node(`v14.16.0`)
+3. yarn(JavaScript package manager)
+4. make
+
+## How to build
+
+1. Install Cargo using [rustup](https://rustup.rs/) with:
+
+```bash
+$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+2. Install node(`v14.16.0`)
+
+3. Install yarn(JavaScript package manager)
+
+4. Build with make:
+
+```bash
+$ make dev-env && \
+	make release
+```
+
+### 5. Install package:
+
+```bash
+$ sudo cp ./target/release/guard /usr/bin/ && \
+	mkdir sudo /etc/guard && \
+	sudo cp config/default.toml /etc/guard/config.toml
+```
+
+### 6. Systemd service configuration:
+
+1. Copy the following to `/etc/systemd/system/guard.service`:
+
+```systemd
+[Unit]
+Description=mCaptcha: a CAPTCHA system that gives attackers a run for their money
+
+[Service]
+Type=simple
+User=mcaptcha
+ExecStart=/usr/bin/guard
+Restart=on-failure
+RestartSec=1
+SuccessExitStatus=3 4
+RestartForceExitStatus=3 4
+SystemCallArchitectures=native
+MemoryDenyWriteExecute=true
+NoNewPrivileges=true
+Environment="RUST_LOG=info"
+
+[Unit]
+After=sound.target
+Wants=network-online.target
+Wants=network-online.target
+Requires=postgresql.service
+After=syslog.target
+
+[Install]
+WantedBy=multi-user.target
+```
+
+2. Enable service:
+```bash
+$ sudo systemctl daemon-reload && \
+	sudo systemctl enable guard && \ # Auto startup during boot
+	sudo systemctl start guard
+``

docs/HACKING.md

@@ -0,0 +1,133 @@
+# Development Setup
+
+## To quickly make changes:
+
+We have a docker-compose config that you can use to quickly spin up dev
+environment.
+
+From the root of the repo, run:
+
+```bash
+$ docker-compose -d up
+```
+
+### Logs from docker:
+
+- Logs from database and web server as they are generated:
+
+```bash
+$ docker-compose logs -f
+```
+
+- from just webserver:
+
+```bash
+$ docker-compose logs -f guard
+```
+
+## Setting up elaborate development environment
+
+### Toolchain
+
+You'll have to install before you can start writing code.
+
+1. Install Rust:
+   Install Cargo(Rust toolchain) using [rustup](https://rustup.rs/) with:
+
+```
+$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+2. Install Node `v14.16.0`:
+   Please refer to [official instructions](https://nodejs.org/en/download/)
+
+3. Install yarn:
+   `npm install -g yarn`
+   For more details, refer to [official
+   instructions](https://yarnpkg.com/getting-started/install)
+
+4. GNU Make:
+   If you are on Linux, it's probably already installed on your machine.
+
+You can check it's existence by running:
+
+```bash
+$ make --version
+```
+
+If it's not available, you download it with your package manager or
+refer to [official instructions](https://www.gnu.org/software/make/)
+
+### External Dependencies:
+
+### Postgres databse:
+
+The backend requires a Postgres database. We have
+compiletime SQL checks so without a database available, you won't be
+able to build the project.
+
+I use Postgres in Docker.
+
+1. To install Docker, please refer to [official
+   instructions](https://docs.docker.com/engine/install/].
+
+2. Create create database user:
+
+```bash
+$ docker create --name mcaptcha-postgres \
+	-e POSTGRES_PASSWORD=password \
+	-p 5432:5432    postgres
+```
+
+3. Start database container:
+
+```bash
+$ docker start mcaptcha-postgres
+```
+
+4. Set configurations:
+
+```bash
+$ cd guard # your copy of https://github.com/mCaptcha/guard
+$ echo 'export DATABASE_URL="postgres://postgres:password@localhost:5432/postgres"' > .env
+```
+
+**NOTE: Don't use this database for other projects**
+
+5. Run migrations:
+   This step is only required when migrations are updated. The server
+   binary has inbuilt migrations manager but that can only be used after
+   the server is compiled. Since we are trying to compile the server here,
+   we can't use that.
+
+However, this project ships with a utility to run migrations!
+
+```bash
+$ cd guard # your copy of https://github.com/mCaptcha/guard
+$ cargo run --bin tests-migrate
+```
+
+That's it, you are all set!
+
+## Build commands:
+
+### Compile:
+
+```bash
+$ cd guard # your copy of https://github.com/mCaptcha/guard
+$ make
+```
+
+### Additional commands:
+
+```bash
+➜  guard git:(master) ✗ make help
+  docs      	- build documentation
+  run       	- run developer instance
+  test 		- run unit and integration tests
+  migrate   	- run database migrations
+  dev-env 	- download dependencies
+  clean     	- drop builds and environments
+  coverage 	- build test coverage in HTML format
+  xml-coverage 	- build test coverage in XML for upload to codecov
+```