gflohr/Lingua-Poly
Lingua-Poly is a system for disassembling natural languages.
:idprefix:
:idseparator: -
:sectanchors:
:sectlinks:
:sectnumlevels: 4
:sectnums:
:toc: macro
:toclevels: 4
:toc-title:
[[lingua-poly]]
= Lingua-Poly
Lingua-Poly is a system for disassembling human languages.
toc::[]
[[status]]
== Status
Pre-alpha, incomplete. This documentation is mostly for the author at the time
of this writing.
The first language being implemented is Finnish. Currently, the present
tense indicative active of Finnish verbs is being implemented.
[[prerequisites]]
== Prerequisites
=== Node.js
https://nodejs.org/[Node.js] is required in order to build or run the front-end.
=== Yarn or NPM
You will also need https://yarnpkg.com/[Yarn].
https://www.npmjs.com[NPM] should work as well.
=== Perl
You need https://www.perl.org/[Perl] in order to run the backend.
Install the required Perl modules with 'cpanm':
[source,bash]
$ cd /path/to/Lingua-Poly
$ cd perl
$ cpanm --installdeps .
$ cpanm -n .
If your current user does not have write permissions for the Perl module
directory, you have to run cpanm with sudo:
[source,bash]
$ cd /path/to/Lingua-Poly
$ cd apis/users
$ sudo cpanm --installdeps .
$ sudo cpanm -n .
One of the indirect dependencies is Authen::Passphrase::Scrypt which may
be difficult to compile. You have to make sure that libcrypto from the
OpenSSL package is installed, and you may have to pass the directories,
where the library file libcrypto.a and the header openssl/aes.h are
found.
For example on Mac OS X with Mac ports you probably have to do something like:
[source,bash]
$ LDFLAGS="-L/opt/local/lib -lcrypto" CFLAGS="-I/opt/local/include" cpanm --installdeps .
Your mileage may vary.
[[getting-started]]
== Getting Started
[[backend]]
=== Backend
A regular backend (API) server is started like this:
[source,bash]
$ cd /path/to/Lingua-Poly
$ cd apis/users
$ perl -Ilib script/lingua-poly-service-users daemon
If you have the web server morby in your $PATH (should be installed as a
dependency), you can also start a development web server that watches for
changes and restarts itself:
[source,bash]
$ cd /path/to/Lingua-Poly
$ cd apis/users
$ morbo script/lingua-poly-service-users
Environment variables:
LINGUA_POLY_USERS_DEBUG::
A list of debugging realms separated by commas, spaces, tabs, colons, or
pipe symbols. The following realms are currently supported:
core::: the core API framework
session::: session handling and controller methods
db::: database-related stuff
request::: set a debugger breakpoint at the beginning of the request handler
all::: all of the above
[[configuration]]
==== Configuration
You need a minimal configuration file lingua-poly-service-users.api.yaml in
http://yaml.org/[YAML] format in the apis/users directory:
[source,yaml]
database:
dbname: linguapoly
user: nobody
secrets:
- SLJao2rSz6GGpWBXcovAVQJfvBFch3kC7AE8QdCeIlt
Make sure that the configured database user has sufficient privileges to
read and write all tables in the database.
Instead of "inventing" a secret, you are advised just omit it initially. The
server application will fail in that case and a randomly generated secret will
be shown in the error message.
[[starting-a-mail-server]]
==== Starting a Mail Server
In development mode, you do not need a real mail server but can start a fake
one:
[source,bash]
$ cd /path/to/Lingua-Poly
$ yarn run maildev
This will start maildev, a development smtp server on your local machine
running on port 1025. This mail server will not deliver any mail but will put
them all into one single mailbox that you can access under
http://localhost:1080.
[[manually-create-passwords]]
==== Manually Create Passwords
TODO! This is outdated.
You can manually create a password (digest) with this one-liner:
[source,bash]
$ perl -Iperl/lib -MLingua::Poly::Util::System -e "print Lingua::Poly::Util::System::crypt_password('admin')"
{ARGON2}$argon2id$v=19$m=32768,t=12,p=1$MTM1QzRDNkEtMDUzOS0xMUVBLUI0NjItM0ZCMDQyNjU0QTBB$tir07b6/y+fWwkvJe9Cw3A
Replace "admin" with a cleartext password.
You can assign this password to user@example.com like this:
[source,bash]
$ echo "UPDATE users SET password = '{SHA512}c7ad44cbad762a5da0a452f9e854fdc1e0e7a52a38015f23f3eab1d80b931dd472634dfac71cd34ebc35d16ab7fb8a90c81f975113d6c7538dc69dd8de9077ec=' WHERE email = 'user@example.com'
Replace "user@example.com" with the user's login, and the part beginning
with {SHA512} with the output of the above one-liner.
[[frontend]]
== Frontend
=== Static Distribution
Build the frontend like this:
[source,bash]
$ cd /path/to/Lingua-Poly
$ yarn run build
yarn run v1.3.2
$ ng build
u Date: 2018-09-15T08:18:32.873Z
Hash: ad5d2f974c866b850a32
Time: 5189ms
chunk {main} main.js, main.js.map (main) 9.38 kB [initial] [rendered]
chunk {polyfills} polyfills.js, polyfills.js.map (polyfills) 227 kB [initial] [rendered]
chunk {runtime} runtime.js, runtime.js.map (runtime) 5.22 kB [entry] [rendered]
chunk {styles} styles.js, styles.js.map (styles) 15.6 kB [initial] [rendered]
chunk {vendor} vendor.js, vendor.js.map (vendor) 2.94 MB [initial] [rendered]
✨ Done in 9.21s.
This will create a directory named 'dist/Lingua-Poly' with all frontend files.
Move the contents of this directory into the document root of your web server
or ...
=== Run Development Version
Alternatively you can run the application with a built-in web server:
[source,bash]
$ cd /path/to/Poly-Lingua
$ yarn start
yarn run v1.3.2
$ ng serve --open
** Angular Live Development Server is listening on localhost:4200, open your browser on http://localhost:4200/ **
...
The application is then available at http://localhost:4200/.
You have to tell the development web server the URI of the backend API
server. The default provided in the file proxy.conf.json should actually just
work if you follow the instructions.
[[copyright]]
== Copyright
Copyright (C) 2018-2019 Guido Flohr guido.flohr@cantanea.com, all rights
reserved.
This library is free software. It comes without any warranty, to the
extent permitted by applicable law. You can redistribute it and/or
modify it under the terms of the Do What the Fuck You Want to Public
License, Version 2, as published by Sam Hocevar. See
http://www.wtfpl.net/ for more details.