forked from okfde/froide-theme
-
-
Notifications
You must be signed in to change notification settings - Fork 5
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: uipa.org specific readme started
- Loading branch information
Showing
1 changed file
with
60 additions
and
55 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,98 +1,103 @@ | ||
| # Froide | ||
| <h1 align="center">UIPA.org</h1> | ||
|
|
||
| [](https://github.com/okfde/froide/actions?query=workflow%3A%22Froide+CI%22) | ||
| <div align="center"> | ||
| :envelope: :rainbow: :office: | ||
| </div> | ||
|
|
||
| Froide is a Freedom Of Information Portal using Django 3.2 on Python 3.8+. | ||
| <div align="center"> | ||
| <strong>A Freedom Of Information Portal for the State of Hawaii</strong> | ||
| </div> | ||
|
|
||
| It is used by the German and the Austrian FOI site, but it is fully | ||
| internationalized and written in English. | ||
| > Note: This is a forked repo with a custom README. For the original document/repo, check out - https://github.com/okfde/froide | ||
| ## Development on Froide | ||
| # Philosophy | ||
|
|
||
| After clone, create a Python 3.8+ virtual environment and install dependencies: | ||
| Getting information from the government is our right under the Freedom of Information Act, however the process is more opaque than you might expect. The Uniform Information Practices Act 92F (UIPA) is Hawaii's adoption of the FOIA. This portal is a way to help individuals through the process of submitting a FOIA request, as well as open sourcing the requests and responses for others to view - all for free! | ||
|
|
||
| ``` | ||
| python3 -m venv froide-env | ||
| source froide-env/bin/activate | ||
| # Development | ||
|
|
||
| # Install dev dependencies | ||
| pip install -r requirements-test.txt | ||
| There are three main things that people have to stand up in order to start developing UIPA. These things are: | ||
|
|
||
| # Install git pre-commit hook | ||
| pre-commit install | ||
| ``` | ||
| 1. The Databases (Elasticsearch & Postgres) | ||
| 2. The Backend (Django development server) | ||
| 3. The Frontend (vite) | ||
|
|
||
| ### Start services | ||
| At the end of setting up your development environment, you should have three terminal windows running each of these separately. | ||
|
|
||
| You can run your own Postgres+PostGIS database and Elasticsearch service or run them with Docker. | ||
| ## The Databases | ||
|
|
||
| You need [docker](https://www.docker.com/community-edition) and [docker-compose](https://docs.docker.com/compose/). Make sure Docker is running and use the following command: | ||
| ### Prerequisites | ||
|
|
||
| ``` | ||
| docker-compose up | ||
| ``` | ||
| - [Docker](https://docs.docker.com/engine/install/) (for the databases) | ||
|
|
||
| ### Instructions | ||
|
|
||
| The databases can be stood up together with one command using the provided [`docker-compose.yml`](https://github.com/CodeWithAloha/uipa/blob/08ce6d39bd9434f739117c801a7b8d442322455e/docker-compose.yml) | ||
|
|
||
| This will start Postgres and Elasticsearch and listen on port 5432 and 9200 respectively. You can adjust the port mapping in the `docker-compose.yml`. | ||
| After running `docker-compose up` successfully, the output in your terminal should look something like: | ||
|
|
||
| ### Setup database and search index, start server | ||
|  | ||
|
|
||
| If you need to adjust settings, you can copy the `froide/local_settings.py.example` to `froide/local_settings.py` and edit it. More steps: | ||
| ## The Backend | ||
|
|
||
| ### Prerequisites | ||
|
|
||
| - [Python 3.8+](https://github.com/CodeWithAloha/uipa/blob/08ce6d39bd9434f739117c801a7b8d442322455e/setup.cfg#L35-L36) (for the backend server) | ||
|
|
||
| ### Instructions | ||
|
|
||
| To run the Django development server, we need to run the following commands: | ||
|
|
||
| ``` | ||
| # Installing dev-dependencies | ||
| pip install -r requirements-test.txt | ||
| # To initialise the database: | ||
| python manage.py migrate --skip-checks | ||
| # Create a superuser | ||
| python manage.py createsuperuser | ||
| # Create and populate search index | ||
| python manage.py search_index --create | ||
| python manage.py search_index --populate | ||
| # Run the Django development server | ||
| python manage.py runserver | ||
| ``` | ||
|
|
||
| ### Run tests | ||
| After running these, you should see something like this in your terminal: | ||
|
|
||
| Make sure the services are running. | ||
|  | ||
|
|
||
| ``` | ||
| # Run all tests | ||
| make test | ||
| # Run only unit/integration tests | ||
| make testci | ||
| # Run only end-to-end tests | ||
| make testui | ||
| ``` | ||
| ## The Frontend | ||
|
|
||
| ### Development tooling | ||
| ### Prerequisites | ||
|
|
||
| For Python code, we use flake8 following black code style. JavaScript, Vue and SCSS files are formatted and linted with ESLint and Prettier. | ||
| - [NodeJS & npm](https://nodejs.org/en/download) (for the frontend) | ||
| - [Yarn](https://classic.yarnpkg.com/en/docs/install) | ||
|
|
||
| Make sure to have pre-commit hooks registered (`pre-commit install`). For VSCode, the [Python](https://code.visualstudio.com/docs/python/linting), [ESLint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) and [Vetur](https://marketplace.visualstudio.com/items?itemName=octref.vetur) extensions are helpful, with these workspace settings recommended: | ||
| ### Instructions | ||
|
|
||
| ```json | ||
| { | ||
| "eslint.format.enable": true, | ||
| "eslint.packageManager": "yarn", | ||
| "vetur.format.defaultFormatter.css": "prettier", | ||
| "vetur.format.defaultFormatter.html": "prettier", | ||
| "vetur.format.defaultFormatter.js": "prettier-eslint" | ||
| } | ||
| ``` | ||
| # Install the dependencies | ||
| yarn install | ||
| ### Upgrade dependencies | ||
|
|
||
| ``` | ||
| # with pip-tools | ||
| pip-compile -U requirements.in | ||
| pip-compile -U requirements-test.in | ||
| # Run the front-end server (vite) | ||
| yarn dev | ||
| ``` | ||
|
|
||
| After performing these steps, the application should be available at http://127.0.0.1:8000/ and look like: | ||
|
|
||
|
|
||
|
|
||
|  | ||
|
|
||
| ## Docs | ||
|
|
||
| [Read the documentation](http://froide.readthedocs.org/en/latest/) including a [Getting Started Guide](http://froide.readthedocs.org/en/latest/gettingstarted/). | ||
|
|
||
| Froide is supported by the [Open Knowledge Foundation Germany](http://www.okfn.de/) and [Open Knowledge Foundation International](http://okfn.org/). | ||
| # Attribution | ||
|
|
||
| ## License | ||
| Many thanks to the [Open Knowledge Foundation Germany](https://www.okfn.de/) for their work on [Froide](https://github.com/okfde/froide). | ||
|
|
||
| Froide is licensed under the MIT License. | ||
| Their docs on the project are available here: [Read the documentation](http://froide.readthedocs.org/en/latest/) including a [Getting Started Guide](http://froide.readthedocs.org/en/latest/gettingstarted/). |