~swalladge/auslan-directory

#Auslan Directory

This is the software powering https://auslan.directory, a community collection of Auslan related resources.

#Contributing

Contributions are welcome! If you wish to contribute changes, please first start a discussion on the dev mailing list and also look for similar items on the bug tracker. Patches can also been emailed to the mailing list.

#Configuration

Configuration is read at runtime from the following locations, in ascending priority order:

Rocket's Config::default()
.env file in current directory or its parents in sequence
.env.local file in current directory or its parents in sequence
environment variables

For variables required by Rocket (the web framework) and their defaults, see https://rocket.rs/master/guide/configuration/#overview. They should be defined in all uppercase, without the ROCKET_ prefix.

See also the following for information on how to format structured values in environment variables:

See .env for example configuration.

#Configuration for development

A simple method is to create a .env.local file (gitignored), and add config there. The .env file in the backend directory is checked into git, and contains the default development config. This should be enough for local development using the instructions in the next section.

#Development

The basic dev flow is:

launch the ephemeral postgres dev server: make dev-db
launch the web server: make run
load fixtures: make fixtures

Make changes, restarting the web server when necessary. There is also make run-watch which auto restarts the server when files change.

Write tests to cover all changes - unit tests for pure functions and end to end tests for overall functionality. Run the tests (see next section on testing), and check the coverage.

Ensure the code is formatted neatly. Run make fix and cd etet && make fix.

#Testing

Unit tests and linting (requires nightly rust, llvm-tools-preview rustup component, and grcov):

$ make test

End to end tests (these are opinionated; see ./run-etet.sh for details):

$ make etet

#Updating dependencies

Install cargo-outdated. Run cargo outdated. For immediate dependencies, manually go through each, update to the latest version, and resolve any breakages.

#Deployment

A successful deployment of this only needs the server binary, a postgresql server, and ideally a reverse proxy or something else to handle ssl.

Build the release binary, using either make build-release, or run a cargo build in release mode as you like. Note that the REVISION environment variable should be set to something unique for each build (suggest using the current git commit hash). This variable controls the path for static assets. The resulting binary can be dropped into a server and run as is, configuring it through the environment.

An opinionated Ansible playbook is included to deploy to an Ubuntu server. (This playbook is not quite complete, and no longer maintained.) May be useful as inspiration.

ansible-playbook ansible/playbook.yml -i path/to/hosts

The production server at https://auslan.directory is deployed using the Dockerfile and fly.io.

#License

Auslan Directory - software powering a website for a community collection of Auslan resources
Copyright (C) 2021 Samuel Walladge

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU Affero General Public License as published by
the Free Software Foundation, version 3 of the License.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU Affero General Public License for more details.

You should have received a copy of the GNU Affero General Public License
along with this program.  If not, see <https://www.gnu.org/licenses/>.

refs

clone