4094bc479788b278cea3ad1f4a3d4ce0ee6ede28 — Martin Angers 3 years ago c22e2b6
Document the getting started cli approach
1 files changed, 38 insertions(+), 3 deletions(-)

M index.md
M index.md => index.md +38 -3
@@ 41,6 41,43 @@ local app = App{

# Getting Started

Unless you want to completely configure the development environment yourself, it is highly recommended to use the `tulip-cli` tool to setup a standard Tulip environment for you. The command can be installed as usual using LuaRocks, and it is recommended to install it in your local tree. You can also install it in the system-wide tree if you prefer.

luarocks install tulip-cli

You should also make sure you have all the tools required to initialize a standard Tulip environment:
* Docker and docker-compose, for the postgresql database (https://docs.docker.com/get-docker/ and https://docs.docker.com/compose/install/)
* The `mkcert` command, to create localhost certificates for https (https://github.com/FiloSottile/mkcert#installation)
    - While not strictly required, this is recommended to minimize differences between your local development environment and the production environment, e.g. to set secure cookies and other https-related headers.
* The `direnv` command, to automatically configure environment variables when you enter your project's directory (https://direnv.net/docs/installation.html)
* It is also recommended to install the postgresql client package, to have access to the `psql` command

Also, before running the `tulip-cli init` command, you should make sure you have [all the prerequisites required to install Tulip][#installation], otherwise it will fail to build some of its dependencies.

Then, assuming the binary directory of your LuaRocks tree is in your `$PATH`, you can initialize a tulip project by running:

tulip-cli init DIR

Where `DIR` is a directory path relative to the current working directory where the command will create and initialize the tulip environment. It must be either a non-existing or an empty directory.

What the command does is:
* Create a project-local luarocks configuration, so that modules are installed locally in the `lua_modules` directory
* Create the project-local directory for the postgresql database, as a docker image that includes the `pg_cron` extension
* Create the secrets for local development, such as the CSRF key, the account key and the root database user's password
* Create the localhost certificates for https support
* Create the `.envrc` direnv file with environment variables to connect to the database and to configure Lua search paths to use the local modules
* Install tulip

After running the command, you should manually:
* Approve the `.envrc` file by running `direnv allow .`
* Bring the database up by running `docker-compose up --build`

# Installation

You must make sure you have the following prerequisites installed on your system prior to installing tulip:

@@ 50,7 87,7 @@ You must make sure you have the following prerequisites installed on your system
* The argon2 development files, required for the `argon2` dependency (Fedora: libargon2-devel)
* The zlib development files, required for the `lua-zlib` dependency (Fedora: zlib-devel)

The preferred method is via LuaRocks:
The preferred method is to use the `tulip-cli` command documented in [Getting Started][#getting-started], but you can also install tulip manually via LuaRocks:

luarocks install tulip

@@ 64,8 101,6 @@ Not all dependencies currently support Lua 5.4 in their official LuaRocks name, 

Everything should work fine when running `luarocks install tulip` (at least on Fedora systems), as it will pull those from my namespace.

# Getting Started

# Architecture

At the core of tulip's architecture is the App's **configuration**, which is a simple Lua table. As such, your application can be as declarative (using the Lua table literal syntax) or as imperative (using Lua code to generate the table) as you want or require.