politeiawww

README

politeiawww

Installing and running

Install dependencies

Go 1.19 or 1.20

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:

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

Git

Installation instructions can be found at https://git-scm.com or https://gitforwindows.org.

$ git version

Install politeia

This step downloads and installs the politeiad and politeiawww binaries. This can be skipped if you already completed it while setting up politeiad.

```
$ 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 MySQL (optional)

This repo includes a script to setup a MySQL user database, it creates the needed databases, the politeiawww user and assigns user privileges. Password authentication is used for all database connections.

Note: This is an optional step. By default, politeiawww will use a LevelDB instance that does not require any additional setup.

The setup script assumes MySQL is running on localhost:3306 and the users will be accessing the databse from localhost. See the setup script comments for more complex setups.

Run the following commands. You will need to replace rootpass with the existing password of your root user. The politeiawwwpass is the password that will be set for the politeiawww user when it's created.

$ cd $GOPATH/src/github.com/decred/politeia/politeiawww/scripts
$ env \
  MYSQL_ROOT_PASSWORD=rootpass \
  MYSQL_POLITEIAWWW_PASSWORD=politeiawwwpass \
  ./userdb-mysql-setup.sh

You will need to use the --userdb=mysql flag when starting politeiawww or add userdb=mysql to the politeiawww.conf file that is setup in the steps below.

An encryption key is required when using a MySQL database, use politeiawww_dbutil cmd tool to create one:

politeiawww_dbutil -createkey 

Setup and run politeiawww

politeiad must already be setup and running before you attempt to run politeiawww.

1. Setup the politeiawww configuration file.

   sample-politeiawww.conf

   Copy the sample configuration file to the politeiawww app data directory. The app data directory will depend on your OS.

   • macOS

     /Users/<username>/Library/Application Support/Politeiawww/politeiawww.conf

   • Windows

     C:\Users\<username>\AppData\Local\Politeiawww/politeiawww.conf

   • Unix

     ~/.politeiawww/politeiawww.conf

   $ mkdir -p ${HOME}/.politeiawww/
   $ cd $GOPATH/src/github.com/decred/politeia/politeiawww
   $ cp ./sample-politeiawww.conf ${HOME}/.politeiawww/politeiawww.conf
   

   Use the following config settings to spin up a development politeiawww instance.

   politeiawww.conf

   ; politeiad host and auth credentials
   rpchost=127.0.0.1
   rpcuser=user
   rpcpass=pass
   rpccert=~/.politeiad/https.cert
   
   testnet=true
   

   Pi configuration

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

   ; Uncomment to enable paywall (optional)
   ; paywallxpub=tpubVobLtToNtTq6TZNw4raWQok35PRPZou53vegZqNubtBTJMMFmuMpWybFCfweJ52N8uZJPZZdHE5SRnBBuuRPfC5jdNstfKjiAs8JtbYG9jx
   ; paywallamount=10000000
   

2. Fetch the politeiad identity. The first time you start politeiawww you will need to fetch the public key that politeiad uses to sign all responses. This is referred to as politeiad's identity and can be retrieved using the --fetchidentity flag. politeiawww will save the identity locally so that this only needs to be done once.

   $ politeiawww --fetchidentity
   

3. Start up politeiawww.

   $ politeiawww
   

API

The politeiawww APIs and politeiawww client can be treated as stable. All other APIs and libraries should be treated as unstable and subject to breaking changes.

Docs:

• Records API docs.
• Legacy Politeiwww API docs - will be deprecated.

Tools and reference clients

• politeiavoter - Tool for voting on Decred proposals using DCR tickets.
• politeiaverify - Tool for verifying data and timestamps downloaded from politeiagui.
• politeiawww_dbutil - Tool for making manual changes to the user database.
• pictl - Reference client for pi, Decred's proposal system.