README.rst 6.6 KB
Newer Older
Vincent Pelletier's avatar
Vincent Pelletier committed
1 2
NEO is a distributed, redundant and scalable implementation of ZODB API.
NEO stands for Nexedi Enterprise Object.
Yoshinori Okuji's avatar
Yoshinori Okuji committed
3

4 5
Overview
========
6

7
A NEO cluster is composed of the following types of nodes:
Vincent Pelletier's avatar
Vincent Pelletier committed
8

9
- "master" nodes (mandatory, 1 or more)
10

11 12 13
  Takes care of transactionality. Only one master node is really active
  (the active master node is called "primary master") at any given time,
  extra masters are spares (they are called "secondary masters").
14

15
- "storage" nodes (mandatory, 1 or more)
16

Julien Muchembled's avatar
Julien Muchembled committed
17 18
  Stores data, preserving history. All available storage nodes are in use
  simultaneously. This offers redundancy and data distribution.
19
  Available backends: MySQL (InnoDB, RocksDB or TokuDB), SQLite
20

21
- "admin" nodes (mandatory for startup, optional after)
Vincent Pelletier's avatar
Vincent Pelletier committed
22

23 24
  Accepts commands from neoctl tool and transmits them to the
  primary master, and monitors cluster state.
Vincent Pelletier's avatar
Vincent Pelletier committed
25

26
- "client" nodes
Vincent Pelletier's avatar
Vincent Pelletier committed
27

28
  Well... Something needing to store/load data in a NEO cluster.
Vincent Pelletier's avatar
Vincent Pelletier committed
29

Julien Muchembled's avatar
Julien Muchembled committed
30 31
ZODB API is fully implemented except:

Julien Muchembled's avatar
Julien Muchembled committed
32 33 34
- pack: only old revisions of objects are removed (it should be possible
  to use `zc.zodbdgc <https://pypi.python.org/pypi/zc.zodbdgc>`_
  for garbage collection)
Julien Muchembled's avatar
Julien Muchembled committed
35 36
- blobs: not implemented (not considered yet)

37
Any ZODB like FileStorage can be converted to NEO instantaneously,
38 39
which means the database is operational before all data are imported.
There's also a tool to convert back to FileStorage.
Julien Muchembled's avatar
Julien Muchembled committed
40

Julien Muchembled's avatar
Julien Muchembled committed
41 42
For more detailed information about features related to scalability,
see the `Architecture and Characteristics` section of https://neo.nexedi.com/.
Julien Muchembled's avatar
Julien Muchembled committed
43

44 45
Requirements
============
Vincent Pelletier's avatar
Vincent Pelletier committed
46

47 48
- Linux 2.6 or later

Julien Muchembled's avatar
Julien Muchembled committed
49
- Python 2.7.x (2.7.9 or later for SSL support)
50

Julien Muchembled's avatar
Julien Muchembled committed
51
- For storage nodes using MySQL backend:
52

53
  - MySQLdb: https://github.com/PyMySQL/mysqlclient-python
54

55
- For client nodes: ZODB 3.10.x or later
Vincent Pelletier's avatar
Vincent Pelletier committed
56

Aurel's avatar
Aurel committed
57
Installation
58
============
Aurel's avatar
Aurel committed
59

Julien Muchembled's avatar
Julien Muchembled committed
60 61
a. NEO can be installed like any other egg (see setup.py). Or you can simply
   make `neo` directory available for Python to import (for example, by
62
   adding its container directory to the PYTHONPATH environment variable).
Vincent Pelletier's avatar
Vincent Pelletier committed
63

Julien Muchembled's avatar
Julien Muchembled committed
64 65
b. Write a neo.conf file like the example provided. If you use MySQL,
   you'll also need create 1 database per storage node.
Vincent Pelletier's avatar
Vincent Pelletier committed
66

67
c. Start all required nodes::
Vincent Pelletier's avatar
Vincent Pelletier committed
68

Julien Muchembled's avatar
Julien Muchembled committed
69 70 71 72
    $ neomaster -f neo.conf
    $ neostorage -f neo.conf -s storage1
    $ neostorage -f neo.conf -s storage2
    $ neoadmin -f neo.conf
Vincent Pelletier's avatar
Vincent Pelletier committed
73

Julien Muchembled's avatar
Julien Muchembled committed
74
d. Tell the cluster to initialize storage nodes::
Vincent Pelletier's avatar
Vincent Pelletier committed
75

Julien Muchembled's avatar
Julien Muchembled committed
76 77 78 79 80 81 82
    $ neoctl -a <admin> start

e. Clients can connect when the cluster is in RUNNING state::

    $ neoctl -a <admin> print cluster
    RUNNING

83
f. See `importer.conf` file to import an existing database,
Julien Muchembled's avatar
Julien Muchembled committed
84 85 86 87
   or `neoctl` command for more administrative tasks.

Alternatively, you can use `neosimple` command to quickly setup a cluster for
testing.
Vincent Pelletier's avatar
Vincent Pelletier committed
88 89

How to use
90
==========
Vincent Pelletier's avatar
Vincent Pelletier committed
91

92 93
First make sure Python can import 'neo.client' package.

94 95
In zope
-------
Aurel's avatar
Aurel committed
96

97
a. Edit your zope.conf, add a neo import and edit the `zodb_db` section by
98 99
   replacing its filestorage subsection by a NEOStorage one.
   It should look like::
Aurel's avatar
Aurel committed
100

101 102 103 104 105 106 107 108
    %import neo.client
    <zodb_db main>
        <NEOStorage>
            master_nodes 127.0.0.1:10000
            name <cluster name>
        </NEOStorage>
        mount-point /
    </zodb_db>
Aurel's avatar
Aurel committed
109

110
b. Start zope
Aurel's avatar
Aurel committed
111

112 113
In a Python script
------------------
Aurel's avatar
Aurel committed
114

115 116 117 118 119
Just create the storage object and play with it::

  from neo.client.Storage import Storage
  s = Storage(master_nodes="127.0.0.1:10010", name="main")
  ...
Aurel's avatar
Aurel committed
120

121 122
"name" and "master_nodes" parameters have the same meaning as in
configuration file.
Aurel's avatar
Aurel committed
123

124 125
Shutting down
-------------
Aurel's avatar
Aurel committed
126

127 128 129
Before shutting down NEO, all clients like Zope instances should be stopped,
so that cluster become idle. This is required for multi-DB setups, to prevent
critical failures in second phase of TPC.
Vincent Pelletier's avatar
Vincent Pelletier committed
130

131 132 133 134 135 136 137 138
A cluster (i.e. masters+storages+admin) can be stopped gracefully by putting it
in STOPPING state using neoctl::

  neoctl -a <admin> set cluster STOPPING

This can also be done manually, which helps if your cluster is in bad state:

- Stop all master nodes first with a SIGINT or SIGTERM, so that storage nodes
139
  don't become in OUT_OF_DATE state.
140
- Next stop remaining nodes with a SIGINT or SIGTERM.
Grégory Wisniewski's avatar
Grégory Wisniewski committed
141

Julien Muchembled's avatar
Julien Muchembled committed
142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158
Master-slave asynchronous replication
-------------------------------------

This is the recommanded way to backup a NEO cluster.
Once a cluster with appropriate `upstream_cluster` & `upstream_masters`
configuration is started, you can switch it into backup mode
using::

  neoctl -a <admin> set cluster STARTING_BACKUP

It remembers it is in such mode when it is stopped, and it can be put back into
normal mode (RUNNING)  by setting it into STOPPING_BACKUP state.

Packs are currently not replicated, which means packing should always be done
up to a TID that is already fully replicated, so that the backup cluster has a
full history (and not random holes).

Julien Muchembled's avatar
Julien Muchembled committed
159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176
SSL support
-----------

In addition to any external solution like OpenVPN, NEO has builtin SSL support
to authenticate and encrypt communications between nodes.

All commands and configuration files have options to specify a CA certificate,
the node certificate and the node private key. A certificate can be shared
by several nodes.

NEO always uses the latest SSL protocol supported by the Python interpreter,
without fallback to older versions. A "SSL: WRONG_VERSION_NUMBER" error means
that a node runs in an older environment (Python + OpenSSL) than others.

Note also that you can't mix non-SSL nodes and SSL nodes, even between a
upstream cluster and a backup one. In doing so, connections can get stuck,
or fail with malformed packets or SSL handshake errors.

177 178
Deployment
==========
Grégory Wisniewski's avatar
Grégory Wisniewski committed
179 180

NEO has no built-in deployment features such as process daemonization. We use
Julien Muchembled's avatar
Julien Muchembled committed
181
`supervisor <http://supervisord.org/>`_ with configuration like below::
Grégory Wisniewski's avatar
Grégory Wisniewski committed
182

183 184
  [group:neo]
  programs=master_01,storage_01,admin
Grégory Wisniewski's avatar
Grégory Wisniewski committed
185

186
  [program:storage_01]
187
  priority=10
Julien Muchembled's avatar
Julien Muchembled committed
188
  command=neostorage -s storage_01 -f /neo/neo.conf
189 190 191

  [program:master_01]
  priority=20
Julien Muchembled's avatar
Julien Muchembled committed
192
  command=neomaster -s master_01 -f /neo/neo.conf
Grégory Wisniewski's avatar
Grégory Wisniewski committed
193

194
  [program:admin]
195
  priority=20
Julien Muchembled's avatar
Julien Muchembled committed
196
  command=neoadmin -s admin -f /neo/neo.conf
Julien Muchembled's avatar
Julien Muchembled committed
197 198 199 200 201

Developers
==========

Developers interested in NEO may refer to
Julien Muchembled's avatar
Julien Muchembled committed
202
`NEO Web site <https://neo.nexedi.com/>`_ and subscribe to following mailing
Julien Muchembled's avatar
Julien Muchembled committed
203 204
lists:

205
- `neo-users <https://mail.tiolive.com/mailman/listinfo/neo-users>`_:
Julien Muchembled's avatar
Julien Muchembled committed
206
  users discussion
207
- `neo-dev <https://mail.tiolive.com/mailman/listinfo/neo-dev>`_:
Julien Muchembled's avatar
Julien Muchembled committed
208
  developers discussion
209 210 211

Automated test results are published at
https://www.erp5.com/quality/integration/P-ERP5.Com.Unit%20Tests/Base_viewListMode?proxy_form_id=WebSection_viewERP5UnitTestForm&proxy_field_id=listbox&proxy_field_selection_name=WebSection_viewERP5UnitTestForm_listbox_selection&reset=1&listbox_title=NEO-%25
Julien Muchembled's avatar
Julien Muchembled committed
212 213 214 215

Commercial Support
==================

Julien Muchembled's avatar
Julien Muchembled committed
216
Nexedi provides commercial support for NEO: https://www.nexedi.com/