Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

multi: Update READMEs. #1421

Merged
merged 2 commits into from Jun 2, 2021
Merged

multi: Update READMEs. #1421

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
07938c8
multi: Update READMEs.
lukebp May 25, 2021
19c68d9
Add API comments.
lukebp May 25, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
48 changes: 6 additions & 42 deletions README.md
View file
Open in desktop
Expand Up @@ -36,47 +36,11 @@ Core software:
* politeiad - Reference server daemon. Data layer.
* politeiawww - Web backend server; depends on politeiad. User layer.

# Installing and running
**The [politeiawww APIs](https://github.com/decred/politeia/tree/master/politeiawww/api/)
and [politeiawww client](https://github.com/decred/politeia/tree/master/politeiawww/client)
can be treated as stable. All other APIs and libraries should be treated as
unstable and subject to breaking changes.**

## Install dependencies
See the politeiad [README](https://github.com/decred/politeia/tree/master/politeiad#politeiad) for instructions on building and running politeiad.

<details><summary><b>Go 1.14 or 1.15</b></summary>

Installation instructions can be found here: https://golang.org/doc/install.
Ensure Go was installed properly and is a supported version:

```sh
$ go version
$ go env GOROOT GOPATH
```

NOTE: `GOROOT` and `GOPATH` must not be on the same path. Since Go 1.8
(2016), `GOROOT` and `GOPATH` are set automatically, and you do not need to
change them. However, you still need to add `$GOPATH/bin` to your `PATH` in
order to run binaries installed by `go get` and `go install` (On Windows,
this happens automatically).

Unix example -- add these lines to .profile:

```
PATH="$PATH:/usr/local/go/bin" # main Go binaries ($GOROOT/bin)
PATH="$PATH:$HOME/go/bin" # installed Go projects ($GOPATH/bin)
```
</details>

<details><summary><b>Git</b></summary>

Installation instructions can be found at https://git-scm.com or
https://gitforwindows.org.
```sh
$ git version
```
</details>

## Build from source

See the politeiad instructions for [building from
source](https://github.com/decred/politeia/tree/master/politeiad#build-from-source).

See the politeiawww instructions for [building from
source](https://github.com/decred/politeia/tree/master/politeiawww#build-from-source).
See the politeiawww [README](https://github.com/decred/politeia/tree/master/politeiawww#politeiawww) for instructions on building and running politeiawww.
171 changes: 120 additions & 51 deletions politeiad/README.md
View file
Open in desktop
@@ -1,68 +1,124 @@
politeiad
====

# Installing and running
## Installing and running

## Install dependencies
### Install dependencies

<details><summary><b>MySQL/MariaDB</b></summary>
<details><summary><b>Go 1.15 or 1.16</b></summary>

Installation instructions can be at https://golang.org/doc/install.
Ensure Go was installed properly and is a supported version:
```
$ go version
$ go env GOROOT GOPATH
```
NOTE: `GOROOT` and `GOPATH` must not be on the same path. Since Go 1.8
(2016), `GOROOT` and `GOPATH` are set automatically, and you do not need to
change them. However, you still need to add `$GOPATH/bin` to your `PATH` in
order to run binaries installed by `go get` and `go install` (On Windows,
this happens automatically).

Unix example -- add these lines to .profile:

Installation instructions can be found at the links below.
MySQL: https://www.mysql.com
MariaDB: https://mariadb.com
```
PATH="$PATH:/usr/local/go/bin" # main Go binaries ($GOROOT/bin)
PATH="$PATH:$HOME/go/bin" # installed Go projects ($GOPATH/bin)
```

</details>

<details><summary><b>Git</b></summary>

## Build from source
Installation instructions can be found at https://git-scm.com or
https://gitforwindows.org.
```
$ git version
```

1. Set the password for the MySQL root user and update the MySQL max
connections settings.
</details>

Max connections defaults to 151 which is not enough for trillian. You will
be prompted for the MySQL root user's password when running these commands.
<details><summary><b>MySQL/MariaDB</b></summary>

```
# Update max connections
$ mysql -u root -p -e "SET GLOBAL max_connections = 2000;"
Installation instructions can be found at the links below.
MySQL: https://www.mysql.com
MariaDB: https://mariadb.com

# Verify the setting
$ mysql -u root -p -e "SHOW VARIABLES LIKE 'max_connections';"
```
Unix example:

You can also update the config file so you don't need to set it manually in
the future. Make sure to restart MySQL once you update the config file.
```
$ sudo apt install mariadb-server
```

MariaDB config file: `/etc/mysql/mariadb.cnf`
MySQL config file: `/etc/mysql/my.cnf`

```
[mysqld]
max_connections = 2000
```
Run the security script to configure MariaDB. You MUST set a password for
the root user. The politeiad scripts will not run properly if the root user
does not have a password.

2. Install trillian v1.3.13.
```
$ sudo mysql_secure_installation
```

```
$ mkdir -p $GOPATH/src/github.com/google/
$ cd $GOPATH/src/github.com/google/
$ git clone git@github.com:google/trillian.git
$ cd trillian
$ git checkout tags/v1.3.13 -b v1.3.13
$ go install -v ./...
```
Update the max connections setting. This is required for politeiad to run
properly. You will be prompted for the MySQL root user's password when
running these commands.

3. Install politeia.
```
# Update max connections
$ mysql -u root -p -e "SET GLOBAL max_connections = 2000;"

```
$ mkdir -p $GOPATH/src/github.com/decred
$ cd $GOPATH/src/github.com/decred
$ git clone git@github.com:decred/politeia.git
$ cd politeia
$ go install -v ./...
```
# Verify the setting
$ mysql -u root -p -e "SHOW VARIABLES LIKE 'max_connections';"
```

You can also update the config file so you don't need to set it manually in
the future. Make sure to restart MySQL once you update the config file.

MariaDB config file: `/etc/mysql/mariadb.cnf`
MySQL config file: `/etc/mysql/my.cnf`

```
[mysqld]
max_connections = 2000
```

</details>

<details><summary><b>Trillian 1.3.13</b></summary>

4. Run the politeiad mysql setup scripts.
Installation instructions can be found at https://github.com/google/trillian.

Unix example:

```
$ mkdir -p $GOPATH/src/github.com/google/
$ cd $GOPATH/src/github.com/google/
$ git clone git@github.com:google/trillian.git
$ cd trillian
$ git checkout tags/v1.3.13 -b v1.3.13
$ go install -v ./...
```

</details>

### Install politeia

This step downloads and installs the politeiad and politeiawww binaries.

You must have all dependencies installed before continuing. The MySQL/MariaDB
root user must have a password and the max connections setting must be updated.
See the MySQL/MariaDB installation section for more details.

```
$ mkdir -p $GOPATH/src/github.com/decred
$ cd $GOPATH/src/github.com/decred
$ git clone git@github.com:decred/politeia.git
$ cd politeia
$ go install -v ./...
```

### Setup and run politeiad

1. Run the politeiad mysql setup scripts.

This will create the politeiad and trillian users as well as creating the
politeiad databases. Password authentication is used for all database
Expand Down Expand Up @@ -91,7 +147,7 @@ politeiad
./tstore-mysql-setup.sh
```

5. Run the trillian mysql setup scripts.
2. Run the trillian mysql setup scripts.

These can only be run once the trillian MySQL user has been created in the
previous step.
Expand All @@ -115,7 +171,7 @@ politeiad
./resetdb.sh
```

6. Start up the trillian instances.
3. Start up trillian.

Running trillian requires running a trillian log server and a trillian log
signer. These are seperate processes that will be started in this step.
Expand Down Expand Up @@ -161,7 +217,7 @@ politeiad
--http_endpoint=localhost:8093
```

7. Setup the politeiad configuration file.
4. Setup the politeiad configuration file.

[`sample-politeiad.conf`](https://github.com/decred/politeia/blob/master/politeiad/sample-politeiad.conf)

Expand All @@ -180,7 +236,7 @@ politeiad

`~/.politeiad/politeiad.conf`

```
```
$ mkdir -p ${HOME}/.politeiad/
$ cd $GOPATH/src/github.com/decred/politeia/politeiad
$ cp ./sample-politeiad.conf ${HOME}/.politeiad/politeiad.conf
Expand All @@ -198,16 +254,22 @@ politeiad

; Tstore settings
dbtype=mysql
```

**Pi configuration**

Pi, Decred's proposal system, requires adding the following additional
settings to your configuration file.

```
; Pi plugin configuration
plugin=pi
plugin=comments
plugin=dcrdata
plugin=ticketvote
plugin=usermd
```

8. Start up the politeiad instance.
5. Start up politeiad.

The password for the politeiad MySQL user must be provided in the `DBPASS`
env variable. The encryption key used to encrypt non-public data at rest
Expand All @@ -220,7 +282,14 @@ politeiad
```
$ env DBPASS=politeiadpass TLOGPASS=tlogpass politeiad
```
## API

- [politeiad API](https://github.com/decred/politeia/tree/master/politeiad/api/v2)
- [politeiad client](https://github.com/decred/politeia/tree/master/politeiad/client)

The politeiad APIs and libraries should be treated as unstable and subject to
breaking changes.

# Tools and reference clients
## Tools and reference clients

* [politeia](https://github.com/decred/politeia/tree/master/politeiad/cmd/politeia) - Reference client for politeiad.