README 5.8 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 19
  Stores data, preserving history. All available storage nodes are in use
  simultaneously. This offers redundancy and data distribution.
  Available backends: MySQL, 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 32 33 34 35 36 37 38 39 40
ZODB API is fully implemented except:

- pack: only old revisions of objects are removed for the moment
        (full implementation is considered)
- blobs: not implemented (not considered yet)

There is a simple way to convert FileStorage to NEO and back again.

See also http://www.neoppod.org/links for more detailed information about
features related to scalability.

41 42
Disclaimer
==========
Vincent Pelletier's avatar
Vincent Pelletier committed
43

44 45
In addition of the disclaimer contained in the licence this code is
released under, please consider the following.
Vincent Pelletier's avatar
Vincent Pelletier committed
46

47 48 49 50
NEO does not implement any authentication mechanism between its nodes, and
does not encrypt data exchanged between nodes either.
If you want to protect your cluster from malicious nodes, or your data from
being snooped, please consider encrypted tunelling (such as openvpn).
Vincent Pelletier's avatar
Vincent Pelletier committed
51

52 53
Requirements
============
Vincent Pelletier's avatar
Vincent Pelletier committed
54

55 56
- Linux 2.6 or later

57
- Python 2.7.x
58

Julien Muchembled's avatar
Julien Muchembled committed
59
- For storage nodes using MySQL backend:
60 61

  - MySQLdb: http://sourceforge.net/projects/mysql-python
62

Julien Muchembled's avatar
Julien Muchembled committed
63
- For client nodes: ZODB 3.10.x
Vincent Pelletier's avatar
Vincent Pelletier committed
64

Aurel's avatar
Aurel committed
65
Installation
66
============
Aurel's avatar
Aurel committed
67

Julien Muchembled's avatar
Julien Muchembled committed
68 69
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
70
   adding its container directory to the PYTHONPATH environment variable).
Vincent Pelletier's avatar
Vincent Pelletier committed
71

Julien Muchembled's avatar
Julien Muchembled committed
72 73
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
74

75
c. Start all required nodes::
Vincent Pelletier's avatar
Vincent Pelletier committed
76

Julien Muchembled's avatar
Julien Muchembled committed
77 78 79 80
    $ 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
81

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

Julien Muchembled's avatar
Julien Muchembled committed
84 85 86 87 88 89 90 91 92 93 94 95
    $ neoctl -a <admin> start

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

    $ neoctl -a <admin> print cluster
    RUNNING

f. See `neomigrate` command to import an existing FileStorage database,
   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
96 97

How to use
98
==========
Vincent Pelletier's avatar
Vincent Pelletier committed
99

100 101
First make sure Python can import 'neo.client' package.

102 103
In zope
-------
Aurel's avatar
Aurel committed
104

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

109 110 111 112 113 114 115 116
    %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
117

118
b. Start zope
Aurel's avatar
Aurel committed
119

120 121
In a Python script
------------------
Aurel's avatar
Aurel committed
122

123 124 125 126 127
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
128

129 130
"name" and "master_nodes" parameters have the same meaning as in
configuration file.
Aurel's avatar
Aurel committed
131

132 133
Shutting down
-------------
Aurel's avatar
Aurel committed
134

135 136 137
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
138

139 140 141 142 143 144 145 146
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
147
   don't become in OUT_OF_DATE state.
148
- Next stop remaining nodes with a SIGINT or SIGTERM.
Grégory Wisniewski's avatar
Grégory Wisniewski committed
149

Julien Muchembled's avatar
Julien Muchembled committed
150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166
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).

167 168
Deployment
==========
Grégory Wisniewski's avatar
Grégory Wisniewski committed
169 170

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

173 174
  [group:neo]
  programs=master_01,storage_01,admin
Grégory Wisniewski's avatar
Grégory Wisniewski committed
175

176
  [program:storage_01]
177
  priority=10
Julien Muchembled's avatar
Julien Muchembled committed
178
  command=neostorage -s storage_01 -f /neo/neo.conf
179 180 181

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

184
  [program:admin]
185
  priority=20
Julien Muchembled's avatar
Julien Muchembled committed
186
  command=neoadmin -s admin -f /neo/neo.conf
Julien Muchembled's avatar
Julien Muchembled committed
187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205

Developers
==========

Developers interested in NEO may refer to
`NEO Web site <http://www.neoppod.org/>`_ and subscribe to following mailing
lists:

- `neo-users <http://mail.tiolive.com/mailman/listinfo/neo-users>`_:
  users discussion
- `neo-dev <http://mail.tiolive.com/mailman/listinfo/neo-dev>`_:
  developers discussion
- `neo-report <http://mail.tiolive.com/mailman/listinfo/neo-report>`_:
  automated test results (read-only list)

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

Nexedi provides commercial support for NEO: http://www.nexedi.com/