Merge pull request #424 from influxdata/quickstart

docs: Update README with quickstart instructions

README.md

@@ -1,11 +1,203 @@
-# Project Delorean
+# InfluxDB IOx
 
-To compile and run this, you'll need:
+TODO: Blog post summary here
 
-- Stable Rust
-- The [`flatc` flatbuffer compiler](https://google.github.io/flatbuffers/flatbuffers_guide_building.html) >= 1.12.0
-- `.env` file in the directory to specify configuration options. You can see an example in the `docs/env.example` file.
+## Quick Start
 
+To compile and run InfluxDB IOx from source, you'll need a Rust compiler and a `flatc` FlatBuffers
+compiler.
 
-## Contributing:
-- Delorean is written mostly in idiomatic Rust -- please see the [Style Guide](docs/style_guide.md) for more details.
+### Cloning the Repository
+
+Using `git`, check out the code by cloning this repository. If you use the `git` command line, this
+looks like:
+
+```
+$ git clone git@github.com:influxdata/influxdb_iox.git
+```
+
+Then change into the directory containing the code:
+
+```
+$ cd influxdb_iox
+```
+
+The rest of the instructions assume you are in this directory.
+
+### Installing Rust
+
+The easiest way to install Rust is by using [`rustup`], a Rust version manager.
+Follow the instructions on the `rustup` site for your operating system.
+
+[`rustup`]: https://rustup.rs/
+
+InfluxDB IOx is currently using a nightly version of Rust to get performance benefits from the
+unstable `simd` feature. The exact nightly version is specified in the `rust-toolchain` file. By
+default, `rustup` will look in this file and automatically install the correct version for you.
+
+### Installing `flatc`
+
+InfluxDB IOx uses the [FlatBuffer] serialization format for its write-ahead log. The [`flatc`
+compiler] reads the schema in `generated_types/wal.fbs` and generates the corresponding Rust code.
+
+Install `flatc` >= 1.12.0 with one of these methods as appropriate to your operating system:
+
+- Using a [Windows binary release]
+- Using the [`flatbuffers` package for conda]
+- Using the [`flatbuffers` package for Arch Linux]
+- Using the [`flatbuffers` package for Homebrew]
+
+Once you have installed the packages, you should be able to run:
+
+```
+$ flatc --version
+```
+
+and see the version displayed.
+
+You won't have to run `flatc` directly; once it's available, Rust's Cargo build tool manages the
+compilation process by calling `flatc` for you.
+
+[FlatBuffer]: https://google.github.io/flatbuffers/
+[`flatc` compiler]: https://google.github.io/flatbuffers/flatbuffers_guide_using_schema_compiler.html
+[Windows binary release]: https://github.com/google/flatbuffers/releases
+[`flatbuffers` package for conda]: https://anaconda.org/conda-forge/flatbuffers
+[`flatbuffers` package for Arch Linux]: https://www.archlinux.org/packages/community/x86_64/flatbuffers/
+[`flatbuffers` package for Homebrew]: https://github.com/Homebrew/homebrew-core/blob/HEAD/Formula/flatbuffers.rb
+
+### Specifying Configuration
+
+**OPTIONAL:** There are a number of configuration variables you can choose to customize by
+specifying values for environment variables in a `.env` file. To get an example file to start from,
+run:
+
+```
+cp docs/env.example .env
+```
+
+then edit the newly-created `.env` file.
+
+For development purposes, the most relevant environment variables are the `INFLUXDB_IOX_DB_DIR` and
+`TEST_INFLUXDB_IOX_DB_DIR` variables that configure where files are stored on disk. The default
+values are shown in the comments in the example file; to change them, uncomment the relevant lines
+and change the values to the directories in which you'd like to store the files instead:
+
+```
+INFLUXDB_IOX_DB_DIR=/some/place/else
+TEST_INFLUXDB_IOX_DB_DIR=/another/place
+```
+
+### Compiling and Starting the Server
+
+InfluxDB IOx is built using Cargo, Rust's package manager and build tool.
+
+To compile for development, run:
+
+```
+$ cargo build
+```
+
+which will create a binary in `target/debug` that you can run with:
+
+```
+$ ./target/debug/influxdb_iox
+```
+
+You can compile and run with one command by using:
+
+```
+$ cargo run
+```
+
+When compiling for performance testing, build in release mode by using:
+
+```
+$ cargo build --release
+```
+
+which will create the corresponding binary in `target/release`:
+
+```
+$ ./target/release/influxdb_iox
+```
+
+Similarly, you can do this in one step with:
+
+```
+$ cargo run --release
+```
+
+The server will, by default, start an HTTP API server on port `8080` and a gRPC server on port
+`8082`.
+
+### Writing and Reading Data
+
+Data can be stored in InfluxDB IOx by sending it in [line protocol] format to the `/api/v2/write`
+endpoint. Data is stored by organization and bucket names. Here's an example using [`curl`] with
+the organization name `company` and the bucket name `sensors` that will send the data in the
+`tests/fixtures/lineproto/metrics.lp` file in this repository, assuming that you're running the
+server on the default port:
+
+```
+curl -v "http://127.0.0.1:8080/api/v2/write?org=company&bucket=sensors" --data-binary @tests/fixtures/lineproto/metrics.lp
+```
+
+[line protocol]: https://docs.influxdata.com/influxdb/v2.0/reference/syntax/line-protocol/
+[`curl`]: https://curl.se/
+
+To query stored data, use the `/api/v2/read` endpoint with a SQL query. This example will return
+all data in the `company` organization's `sensors` bucket for the `processes` measurement:
+
+```
+$ curl -v -G -d 'org=company' -d 'bucket=sensors' --data-urlencode 'sql_query=select * from processes' "http://127.0.0.1:8080/api/v2/read"
+```
+
+## Contributing
+
+If you want to contribute to InfluxDB IOx you will need to sign InfluxData's CLA, which can be
+found with more information [on our website].
+
+[on our website]: https://www.influxdata.com/legal/cla/
+
+InfluxDB IOx is written mostly in idiomatic Rust -- please see the [Style Guide] for more details.
+
+[Style Guide]: docs/style_guide.md
+
+### Running Tests
+
+The `cargo` build tool runs tests as well. Run:
+
+```
+$ cargo test --workspace
+```
+
+### Running `rustfmt` and `clippy`
+
+CI will check the code formatting with [`rustfmt`] and Rust best practices with [`clippy`].
+
+To automatically format your code according to `rustfmt` style, first make sure `rustfmt` is installed using `rustup`:
+
+```
+$ rustup component add rustfmt
+```
+
+Then, whenever you make a change and want to reformat, run:
+
+```
+$ cargo fmt --all
+```
+
+Similarly with `clippy`, install with:
+
+```
+$ rustup component add clippy
+```
+
+And run with:
+
+```
+$ cargo clippy  --all-targets --workspace
+```
+
+[`rustfmt`]: https://github.com/rust-lang/rustfmt
+[`clippy`]: https://github.com/rust-lang/rust-clippy