aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--readme.md74
1 files changed, 74 insertions, 0 deletions
diff --git a/readme.md b/readme.md
index 795b00e..4b6e222 100644
--- a/readme.md
+++ b/readme.md
@@ -72,6 +72,80 @@ retained.
72* `./flake.nix`: project runtime and development environment description 72* `./flake.nix`: project runtime and development environment description
73 73
74 74
75## Development environment
76
77The development and execution environment is fully described using the [Nix]
78language and package manager as a [Nix Flake] in `./flake.nix`. This allows
79creating reproducible environments containing all the software dependencies of
80the program itself, as well as optional development tools.
81
82(_Note: this projects requires Nix version 2.4 or higher_).
83
84[Nix]: https://nixos.org/guides/how-nix-works.html
85[Nix Flake]: https://www.tweag.io/blog/2020-05-25-flakes/
86
87This environment can be used on NixOS, MacOS, or any Linux system having Nix
88installed. In principle, Nix should also be usable on Windows through the
89Windows Subsystem for Linux ([WSL]) compatibility layer. Full virtual machines
90and containers can also be derived from the same description file.
91
92[WSL]: https://docs.microsoft.com/en-us/windows/wsl/about
93
94All the commands in this section have to be run within the provided development
95shell, which can be entered by running the following command at the root
96directory of the project:
97
98```sh
99nix develop
100```
101
102### Local database
103
104The Nix Flake development shell provides its own self-contained PostgreSQL
105server, configured to operate independently of any other instances running on
106the same system.
107
108All data are written to the `./development_database/pgadata` directory. The
109database server can be initialised by running the following command:
110
111```sh
112initdb --no-locale --encoding UTF8 --auth-host reject --auth-local peer
113```
114
115The local development PostgreSQL server can then be started by running the
116following command, with the `$PGHOST` environment variable automatically set
117by the development shell:
118
119```sh
120postgres -h "" -k "$PGHOST" -d 2
121```
122
123This server listens to local requests through a UNIX domain socket located at
124`./development_database/.s.PGSQL.5432`, to which programs run in the
125development shell will implicitly automatically connect to.
126
127The development shell ships with both the `psql` and [`pgcli`][pgcli] tools to
128interact directly with the database. The latter provides additional features
129such as syntax highlighting and better auto-completion.
130
131[pgcli]: https://www.pgcli.com/
132
133A new local database for the application can be created and its table can be
134initialised with:
135
136```sh
137createdb app
138psql app < ./sql/tables.sql
139```
140
141Should the need arise, this database can be deleted with the following command
142before being created and initialised again:
143
144```sh
145dropdb app
146```
147
148
75## Copyright and licensing 149## Copyright and licensing
76 150
77Copyright (C) 2021 Pacien TRAN-GIRARD. 151Copyright (C) 2021 Pacien TRAN-GIRARD.