github.com/decred/politeia@v1.4.0/politeiad/README.md (about)

     1  politeiad
     2  ====
     3  
     4  ## Installing and running
     5  
     6  ### Install dependencies
     7  
     8  <details><summary><b>Go 1.18 or 1.19</b></summary>
     9  
    10    Installation instructions can be at https://golang.org/doc/install.
    11    Ensure Go was installed properly and is a supported version:
    12    ```
    13    $ go version
    14    $ go env GOROOT GOPATH
    15    ```
    16    NOTE: `GOROOT` and `GOPATH` must not be on the same path. Since Go 1.8
    17    (2016), `GOROOT` and `GOPATH` are set automatically, and you do not need to
    18    change them. However, you still need to add `$GOPATH/bin` to your `PATH` in
    19    order to run binaries installed by `go get` and `go install` (On Windows,
    20    this happens automatically).
    21  
    22    Unix example -- add these lines to .profile:
    23  
    24    ```
    25    PATH="$PATH:/usr/local/go/bin"  # main Go binaries ($GOROOT/bin)
    26    PATH="$PATH:$HOME/go/bin"       # installed Go projects ($GOPATH/bin)
    27    ```
    28  
    29  </details>
    30  
    31  <details><summary><b>Git</b></summary>
    32  
    33    Installation instructions can be found at https://git-scm.com or
    34    https://gitforwindows.org.
    35    ```
    36    $ git version
    37    ```
    38  
    39  </details>
    40  
    41  <details><summary><b>MySQL/MariaDB</b></summary>
    42  
    43    Installation instructions can be found at the links below.  
    44    MySQL: https://www.mysql.com  
    45    MariaDB: https://mariadb.com  
    46  
    47    Unix example:  
    48  
    49    ```
    50    $ sudo apt install mariadb-server
    51    ```
    52  
    53    Run the security script to configure MariaDB. You MUST set a password for
    54    the root user. The politeiad scripts will not run properly if the root user
    55    does not have a password.  
    56  
    57    ```
    58    $ sudo mysql_secure_installation
    59    ```
    60  
    61    Update the max connections setting. This is required for politeiad to run
    62    properly. You will be prompted for the MySQL root user's password when
    63    running these commands.  
    64  
    65    ```
    66    # Update max connections    
    67    $ mysql -u root -p -e "SET GLOBAL max_connections = 2000;"
    68  
    69    # Verify the setting
    70    $ mysql -u root -p -e "SHOW VARIABLES LIKE 'max_connections';"
    71    ```
    72  
    73    You can also update the config file so you don't need to set it manually in
    74    the future.  Make sure to restart MySQL once you update the config file.  
    75  
    76    MariaDB config file: `/etc/mysql/mariadb.cnf`  
    77    MySQL config file: `/etc/mysql/my.cnf`  
    78  
    79    ```
    80    [mysqld]
    81    max_connections = 2000
    82    ```
    83  
    84  </details>
    85  
    86  <details><summary><b>Trillian 1.4.1</b></summary>
    87  
    88    Installation instructions can be found at https://github.com/google/trillian.
    89  
    90    Unix example:
    91  
    92    ```
    93    $ mkdir -p $GOPATH/src/github.com/google/
    94    $ cd $GOPATH/src/github.com/google/
    95    $ git clone git@github.com:google/trillian.git
    96    $ cd trillian
    97    $ git checkout tags/v1.4.1 -b v1.4.1
    98    $ go install -v ./...
    99    ```
   100  
   101  </details>
   102  
   103  ### Install politeia
   104  
   105  This step downloads and installs the politeiad and politeiawww binaries.  
   106  
   107  You must have all dependencies installed before continuing. The MySQL/MariaDB
   108  root user must have a password and the max connections setting must be updated.
   109  See the MySQL/MariaDB installation section for more details.
   110  
   111    ```
   112    $ mkdir -p $GOPATH/src/github.com/decred
   113    $ cd $GOPATH/src/github.com/decred
   114    $ git clone git@github.com:decred/politeia.git
   115    $ cd politeia
   116    $ go install -v ./...
   117    ```
   118  
   119  ### Setup and run politeiad
   120  
   121  1. Run the politeiad mysql setup scripts.
   122  
   123     This will create the politeiad and trillian users as well as creating the
   124     politeiad databases. Password authentication is used for all database
   125     connections.
   126  
   127     **The password that you set for the politeiad MySQL user will be used to
   128     derive an encryption key that is used to encrypt non-public data at rest.
   129     Make sure to setup a strong password when running in production. Once set,
   130     the politeiad user password cannot change.**
   131  
   132     The setup script assumes MySQL is running on `localhost:3306` and the users
   133     will be accessing the databse from `localhost`. See the setup script
   134     comments for more complex setups.
   135  
   136     Run the following commands. You will need to replace `rootpass` with the
   137     existing password of your root user. The `politeiadpass` and `trillianpass`
   138     are the password that will be set for the politeiad and trillian users when
   139     the script creates them.
   140  
   141      ```
   142      $ cd $GOPATH/src/github.com/decred/politeia/politeiad/scripts
   143      $ env \
   144        MYSQL_ROOT_PASSWORD=rootpass \
   145        MYSQL_POLITEIAD_PASSWORD=politeiadpass \
   146        MYSQL_TRILLIAN_PASSWORD=trillianpass \
   147        ./tstore-mysql-setup.sh
   148      ```
   149  
   150  2. Run the trillian mysql setup scripts.
   151  
   152     These can only be run once the trillian MySQL user has been created in the
   153     previous step.
   154  
   155     The `trillianpass` and `rootpass` will need to be updated to the passwords
   156     for your trillian and root users.
   157  
   158     If setting up a mainnet instance, change the `MYSQL_DATABASE` env variable
   159     to `mainnet_trillian`.
   160  
   161      ```
   162      $ cd $GOPATH/src/github.com/google/trillian/scripts
   163  
   164      # Testnet setup
   165      $ env \
   166        MYSQL_USER=trillian \
   167        MYSQL_PASSWORD=trillianpass \
   168        MYSQL_DATABASE=testnet3_trillian \
   169        MYSQL_URI="${MYSQL_USER}:${MYSQL_PASSWORD}@tcp(127.0.0.1:3306)/${MYSQL_DATABASE}" \
   170        MYSQL_ROOT_PASSWORD=rootpass \
   171        ./resetdb.sh
   172      ```
   173  
   174  3. Start up trillian.
   175  
   176     Running trillian requires running a trillian log server and a trillian log
   177     signer. These are seperate processes that will be started in this step. 
   178  
   179     You will need to replace the `trillianpass` with the trillian user's
   180     password that you setup in previous steps. The commands below for testnet
   181     and mainnet run the trillian instances on the same ports so you can only
   182     run one set of commands, testnet or mainnet. Run the testnet commands if
   183     you're setting up a development environment.
   184  
   185     If setting up a mainnet instance, change the `MYSQL_DATABASE` env variable
   186     to `mainnet_trillian` for both the log server and log signer.
   187  
   188  
   189     Start testnet log server
   190      ```
   191      $ export MYSQL_USER=trillian && \
   192        export MYSQL_PASSWORD=trillianpass && \
   193        export MYSQL_DATABASE=testnet3_trillian && \
   194        export MYSQL_URI="${MYSQL_USER}:${MYSQL_PASSWORD}@tcp(127.0.0.1:3306)/${MYSQL_DATABASE}"
   195  
   196      $ trillian_log_server \
   197        --mysql_uri=${MYSQL_URI} \
   198        --mysql_max_conns=2000 \
   199        --rpc_endpoint localhost:8090 \
   200        --http_endpoint localhost:8091 \
   201        --logtostderr ...
   202      ```
   203  
   204     Start testnet log signer
   205      ```
   206      $ export MYSQL_USER=trillian && \
   207        export MYSQL_PASSWORD=trillianpass && \
   208        export MYSQL_DATABASE=testnet3_trillian && \
   209        export MYSQL_URI="${MYSQL_USER}:${MYSQL_PASSWORD}@tcp(127.0.0.1:3306)/${MYSQL_DATABASE}"
   210  
   211      $ trillian_log_signer --logtostderr --force_master \
   212        --batch_size=1000 \
   213        --sequencer_guard_window=0 \
   214        --sequencer_interval=200ms \
   215        --mysql_uri=${MYSQL_URI} \
   216        --rpc_endpoint localhost:8092 \
   217        --http_endpoint=localhost:8093 
   218      ```
   219  
   220  4. Setup the politeiad configuration file.
   221  
   222     [`sample-politeiad.conf`](sample-politeiad.conf)
   223  
   224     Copy the sample configuration file to the politeiad app data directory. The
   225     app data directory will depend on your OS.
   226  
   227     * **macOS**
   228  
   229       `/Users/<username>/Library/Application Support/Politeiad/politeiad.conf`
   230  
   231     * **Windows**
   232  
   233       `C:\Users\<username>\AppData\Local\Politeiad/politeiad.conf`
   234  
   235     * **Unix**
   236  
   237       `~/.politeiad/politeiad.conf`
   238  
   239      ```
   240      $ mkdir -p ${HOME}/.politeiad/
   241      $ cd $GOPATH/src/github.com/decred/politeia/politeiad
   242      $ cp ./sample-politeiad.conf ${HOME}/.politeiad/politeiad.conf
   243      ```
   244  
   245      Use the following config settings to spin up a development politeiad
   246      instance.
   247  
   248     **politeiad.conf**
   249  
   250      ```
   251      ; politeiad settings
   252      rpcuser=user
   253      rpcpass=pass
   254      testnet=true
   255  
   256      ; tstore settings
   257      dbtype=mysql
   258      ```
   259  
   260      **Pi configuration**
   261  
   262      Pi, Decred's proposal system, requires adding the following additional
   263      settings to your configuration file.  
   264  
   265      ```
   266      ; Pi plugin configuration
   267      plugin=pi
   268      plugin=comments
   269      plugin=dcrdata
   270      plugin=ticketvote
   271      plugin=usermd
   272      pluginsetting=comments,allowextradata,1
   273      ```
   274  5. Start up politeiad.
   275  
   276     The password for the politeiad MySQL user must be provided in the `DBPASS`
   277     env variable. The encryption key used to encrypt non-public data at rest
   278     will be derived from the `DBPASS`. The `DBPASS` cannot change.
   279  
   280     ```
   281     $ env DBPASS=politeiadpass politeiad
   282     ```
   283  
   284  ## Politeiad API
   285  
   286  - [politeiad API](api/v2)
   287  - [politeiad client](client/)
   288  
   289  The politeiad APIs and libraries should be treated as unstable and subject to
   290  breaking changes.
   291  
   292  ## Plugins
   293  
   294  The basic politeiad API allows users to submit and edit records, where a record
   295  is an arbitrary set of files. A Decred proposal is an example of a record.
   296  
   297  politeiad uses a plugin architecture to extend records with additional
   298  functionality. For example, the comments plugin extends a record with comment
   299  functionality. It provides an API for creating, editing, deleting, and
   300  retrieving comments.
   301  
   302  The plugins and their APIs can be found [here](plugins/).
   303  
   304  Plugins can be specified using the `--plugin` flag or a `plugin` config file
   305  entry.
   306  
   307  Plugins have default settings that can be overridden using the
   308  `--pluginsetting` flag or a `pluginsetting` config file entry. Plugin settings
   309  are key-value settings that must use the format:
   310  
   311      pluginID,key,value
   312  
   313  The list of settings for each plugin can be found in the [plugin
   314  APIs](plugins/).
   315  
   316  The following example shows what an entry in the politeiad config file would
   317  look like if the user wanted to override the default comments plugin setting
   318  for a maximum comment length. This would set the max comment length to 2500
   319  characters.
   320  
   321      pluginsetting=comments,commentlengthmax,2500
   322  
   323  Some plugin settings require multiple values to be provided. One such example
   324  is when a list of supported characters is required. You can provide multiple
   325  values for a single plugin setting by passing the values in an array. The
   326  array must be a valid JSON encoded []string.
   327  
   328      # Easiest method
   329      pluginsetting=pluginID,key,["value1","value2","value3"]
   330  
   331      # Or you can manually escape the quotes
   332      pluginsetting="pluginID,key,[\"value1\",\"value2\",\"value3\"]"
   333  
   334  ## Tools and reference clients
   335  
   336  * [politeia](cmd/politeia) - Reference client for politeiad.
   337  
   338  ## Development
   339  
   340  ### Reset databases
   341  
   342  You can remove all records from politeiad using the following commands.
   343  
   344  These commands will not delete any politeiawww user data. This lets you reset
   345  the politeiad data to clear out all existing records while still keeping all of
   346  your politeiawww user accounts intact so that you can have a fresh development
   347  enviroment without needing to re-setup the user accounts.
   348  
   349    ```
   350    # Reset politeiad database
   351    $ cd ${HOME}/go/src/github.com/decred/politeia/
   352    $ env MYSQL_ROOT_PASSWORD="rootpass" \
   353      .politeiad/scripts/tstore-mysql-reset.sh
   354  
   355    # Reset trillian database
   356    $ cd ${HOME}/go/src/github.com/google/trillian/
   357    $ export MYSQL_USER=trillian && \
   358      export MYSQL_PASSWORD=trillianpass && \
   359      export MYSQL_DATABASE=testnet3_trillian && \
   360      export MYSQL_ROOT_PASSWORD=rootpass && \
   361      ./scripts/resetdb.sh
   362  
   363    # Reset cached data. The location of this directory will depend on your
   364    # operating system.
   365    rm -rf ~/.politeiad/data/testnet3
   366    ```