# # # patch "monotone.texi" # from [11687dcc11a586d90f591c8a91efb8ddb1028b82] # to [4f56bce915030236cbb39ca5a2564fc48e60bda9] # ============================================================ --- monotone.texi 11687dcc11a586d90f591c8a91efb8ddb1028b82 +++ monotone.texi 4f56bce915030236cbb39ca5a2564fc48e60bda9 @@ -1086,10 +1086,12 @@ * Starting a New Project:: * Adding Files:: * Committing Work:: -* Network Service:: +* Basic Network Service:: +* Synchronising Databases:: * Making Changes:: * Dealing with a Fork:: * Branching and Merging:: +* Network Service Revisited:: @end menu @@ -1567,14 +1569,17 @@ yet, it has no descendents. @page address@hidden Network Service address@hidden Network Service address@hidden Basic Network Service address@hidden Basic Network Service Jim now decides he will make his base revision available to his -employees. To do this he gives Abe and Beth permission to access his -database. There are two parts to this: first, he has to get a copy of -each of their public keys; then, he has to tell monotone that the -holders of those keys are permitted to access his database. +employees. To do this, he arranges for Abe and Beth to synchronise +their databases with his, over the network. There are two +pre-requisites for this: first, he has to get a copy of each of their +public keys; then, he has to tell monotone that the holders of those +keys are permitted to access his database. Finally, with these +pre-requisites in place, he needs to tell monotone to provide network +access to his database. First, Abe exports his public key: @@ -1606,13 +1611,13 @@ @end smallexample Then Abe and Beth both send their keys to Jim. The keys are not secret, -but the team members must be relatively certain that they are -communicating with the person they intend to trust, when exchanging -keys, and not some malicious person pretending to be a team -member. Key exchange may involve sending keys over an encrypted -medium, or meeting in person to exchange physical copies, or any -number of techniques. All that matters, ultimately, is that Jim receives -both Abe's and Beth's key. +but the team members must be relatively certain that they are exchanging +keys with the person they intend to trust, and not some malicious person +pretending to be a team member. Key exchange may involve sending keys +over an encrypted medium, or meeting in person to exchange physical +copies, or any number of techniques. All that matters, ultimately, is +that Jim receives both Abe's and Beth's key in a way that he can be sure +of. So eventually, after key exchange, Jim has the public key files in his home directory. He tells monotone to read the associated key packets @@ -1644,7 +1649,11 @@ @end group @end smallexample -He then makes sure that his TCP port 5253 is open to incoming +These files are read by the default monotone hooks that will decide +whether remote monotone users will be allowed access to Jim's database, +identified by the named keys. + +Jim then makes sure that his TCP port 5253 is open to incoming connections, adjusting his firewall settings as necessary, and runs the monotone @command{serve} command: @@ -1661,26 +1670,13 @@ around @code{"jp.co.juicebot.jb7*"} are there to protect the @code{*} from expansion by the shell; they have no meaning to monotone. -If you want to be more -restrictive in which interfaces you listen on, or use a non-standard port, -you can use the @code{--bind=address:port} argument like so: address@hidden address@hidden Synchronising Databases address@hidden Synchronising Databases address@hidden address@hidden -$ monotone --db=jim.db --bind=localhost:1234 "jp.co.juicebot.jb7*" address@hidden group address@hidden smallexample +With Jim's server preparations done, now Abe is ready to fetch Jim's +code. To do this he issues the monotone @code{sync} command: -The example above will start monotone listening on port 1234 only -on the loopback interface 127.0.0.1 (which is not accessible -from the network, so you can use it for testing without -exposing an open port to the rest of the world). -You can cause monotone to listen on all interfaces on -port 1234 by leaving out the address part like @code{--bind=:1234}. - -Now Abe decides he wishes to fetch Jim's code. To do this he issues -the monotone @code{sync} command: - @smallexample @group $ monotone --db=abe.db sync jim-laptop.juicebot.co.jp "jp.co.juicebot.jb7*" @@ -1701,30 +1697,28 @@ Abe now has, in his database, a copy of everything Jim put in the branch. Therefore Abe can disconnect from the expensive network -connection he's on and work locally for a while. When Abe wants to -send work back to Jim, or get new work Jim has added, all he needs to -do is run the @command{sync} command again and work will flow both -ways, bringing each party up to date with the work of the other. +connection he's on and work locally for a while. Remember that, in +monotone, work is done between working directories in the filesystem and +the local database; network connectivity is necessary only when that +work is to be shared with others. -At this point Jim is operating as a sort of ``central server'' for the -company. If Jim wants to, he can leave his server running forever, or -even put his server on a dedicated computer with better network -connectivity. But if Jim is ever unable to play this role of ``central -server'', perhaps due to a network failure, either Beth or Abe can run -the @command{serve} command and provide access for the other to address@hidden with. In fact, each employee can run a server if they -like, concurrently, to help minimize the risk of service disruption from -hardware failures. Changes will flow between servers automatically as -clients access them and trade with one another. +As we follow the juicebot team through the next several steps, we'll see +them run the @command{sync} command again with Jim, and work will flow +both ways. The first time you @command{sync} a new database, monotone +remembers the server and branch patterns you use, and makes them the +default for future operations. -In practice, most people like to use at least one central server that is -always running; this way, everyone always knows where to go to get the -latest changes, and people can push their changes out without first -calling their friends and making sure that they have their servers -running. To make this style of working more convenient, monotone -remembers the first server you use, and makes that the default for -future operations. +At the end of each exchange, information about all changes in the branch +known to each database have been sent to the other party - including the +work of the third team member that had previously been exchanged. As +well as allowing each team member to learn about the others' work, this +also means that each party's laptop contains a @emph{backup} of the +others' work too. +Jim, Abe and Beth will continue working like this while they're getting +started, and we'll revisit the issue of network service with them a +little later as the project grows. + @page @node Making Changes @section Making Changes @@ -2245,6 +2239,125 @@ Whatever arrangement of branches you come up with, though, monotone should be able to handle it. address@hidden address@hidden Network Service Revisited address@hidden Network Service Revisited + +Up until now, Jim has been using his laptop and database as a sort of +``central server'' for the company; Abe and Beth have been syncing with +Jim, and learning of each other's work via Jim's database. This has +worked fine while the product has been in early development; Jim has +good network connectivity in Japan, and has been staying home +concentrating on programming. He has been able to leave his laptop +connected and running all the time, while his employees in different +time-zones work and sync their databases. This is now starting to +change, and two problems are starting to cause occasional difficulties. + +Firstly, Jim is finding that he has to spend more of his time +travelling, demonstrating the new juicebot features to customers; thus +his laptop is spending more time disconnected from the network, or +connected at dynamic addresses where it's not convenient for Abe and +Beth to find him and sync. This doesn't prevent them doing any work, but +it does have some uncomfortable consequences: they're more likely to +have to manually merge conflicting changes when they finally sync up and +discover they've both come up with slightly different fixes for the same +bug in the meantime, and they're more exposed to loss of work if one of +them suffers a disk failure before they've had a chance to sync that +work with another database. + +Secondly, the level of project activity is picking up, and there are +more and more changes to be synced in the narrower window of time while +Jim is connected. Because Jim has been using the one database file both +for his own local work, and for serving to the others in the team, Jim +occasionally finds that the monotone serve process (busy syncing with +Abe or Beth) has a lock on the database, while he's trying to do local +work like updates or commits. He finds he sometimes needs to take down +the server process to do this local work, further exacerbating the first +problem. + +The juicebot team are resourceful, and by now quite used to working +independently. While Jim has been away travelling, Abe and Beth have +come up with their own solution to the first problem: they'll run +servers from their databases, setting them up just like Jim did +previously. That way, if Jim's database is offline, either Beth or Abe +can run the @command{serve} command and provide access for the other to address@hidden with. When Jim reappears, the next person to address@hidden with him will often pass him information about both +employees' work that they've sync'ed with eachother in the meantime, +just as he used to do. In fact, Jim now finds it more convenient to +initiate the sync with one of the other servers when he has a spare +moment and dynamic connectivity from a hotel room or airport. Changes +will flow between servers automatically as clients access them and trade +with one another. + +This gets them by for a while, but now Beth and Abe start to experience +the database locking issues too. They don't always have reliable network +connectivity, so sometimes Jim finds that neither of them is online to +sync with when he has the chance. Jim now also has several customers +interested in beta-testing the new code, and following updates as the +bugs and issues they report are addressed. + +Jim decides it's time for a permanent server they can all sync with; +this way, everyone always knows where to go to get the latest changes, +and people can push their changes out without first calling their +friends and making sure that they have their servers running. + +Jim has rented some web server space on a service provider's shared +system for the JuiceBot, Inc public website; he thinks this server will +be a good place to host the central monotone server too. He sets up a +new monotone database on the server, and generates a new key specially +for the server (so he doesn't have to expose his own development private +key on the shared system). He sets up the permissions files, and +arranges for the monotone @command{serve} command to be started each +time the server reboots. + +Because he's running on a shared server, Jim needs to be a little more +restrictive about which interfaces and addresses his new server process +will listen on. He should only accept connections at the address used +for his website, because some of the provider's other customers might +also want to publish their own monotone projects on this server. In the +startup script for the server, Jim uses the @code{--bind=address:port} +argument like so: + address@hidden address@hidden +$ monotone --db=server.db --bind=www.juicebot.co.jp "jp.co.juicebot.jb7*" address@hidden group address@hidden smallexample + +The example above will start monotone listening on the default port +(5253), but only on the IP address associated with www.juicebot.co.jp. +Jim can do this because his hosting provider has given him a dedicated +IP address. If the hosting provider offered only a single shared IP +address belonging to the server, each customer could bind a different +port number on that address. + +While he's first testing the setup, Jim uses address@hidden:1234}. This causes the monotone process to listen +only to port 1234 on the loopback interface 127.0.0.1, which is not +accessible from the network, so Jim doesn't expose an open port to the +rest of the world until he's satisifed with the permissions +configuration. You can cause monotone to listen on all interfaces on +port 1234 by leaving out the address part like @code{--bind=:1234}. + +When he's satisified the server is set up correctly, Jim does an initial address@hidden with the new database, filling it with all the revision +history currently on his laptop; it will catch up with Abe and Beth's +latest work when they next sync, too. + +All of the team members now want to sync with the new monotone server by +default, so they reset their local database variables accordingly. + +Jim knows he doesn't have to keep a special backup of the new server's +contents; if the server should fail, all the contents of its database +can be found amongst the other team members. He does, however, take a +copy of the server's private key, so he can restore that if necessary. +Jim also knows that even if someone should break into the shared hosting +server and tamper with the database, they won't be able to inject +malicious code into the project, because all revisions are signed by the +team members, and he doesn't trust the server key for signing revisions. + + @node Advanced Uses @chapter Advanced Uses