| commit | author | age | ||
| 148b40 | 1 | ## Ticket Replication & Advanced Administration |
| JM | 2 | |
| 3 | *SINCE 1.4.0* | |
| 4 | ||
| 5 | **Ticket Replication** | |
| 6 | Gitblit does *not* provide a generic/universal replication mechanism that works across all persistence backends. | |
| 7 | ||
| 8 | **Advanced Administration** | |
| 9 | Gitblit does *not* provide a generic/universal for advanced administration (i.e. manually tweaking ticket data) however each service does have a strategy for that case. | |
| 10 | ||
| 11 | ### FileTicketService | |
| 12 | ||
| 13 | #### Ticket Replication | |
| 14 | Replication is not supported. | |
| 15 | ||
| 16 | #### Advanced Administration | |
| 17 | Use your favorite text editor to **carefully** manipulate a ticket's journal file. I recommend using a JSON validation service to ensure your changes are valid JSON. | |
| 18 | ||
| 19 | After you've done this, you will need to reset Gitblit's internal ticket cache and you may need to reindex the tickets, depending on your changes. | |
| 20 | ||
| 21 | ### BranchTicketService | |
| 22 | ||
| 23 | #### Ticket Replication | |
| 24 | Gitblit supports ticket replication for a couple of scenarios with the *BranchTicketService*. This requires that the Gitblit instance receiving the ticket data be configured for the *BranchTicketService*. Likewise, the source of the ticket data must be a repository that has ticket data persisted using the *BranchTicketService*. | |
| 25 | ||
| c134a0 | 26 | ##### Manually Pushing refs/meta/gitblit/tickets |
| 148b40 | 27 | |
| JM | 28 | Let's say you wanted to create a perfect clone of the Gitblit repository hosted at https://dev.gitblit.com in your own Gitblit instance. We'll use this repository as an example because it is configured for the *BranchTicketService*. |
| 29 | ||
| 30 | **Assumptions** | |
| 31 | ||
| 32 | 1. We are pushing to our local Gitblit with the admin account, or some other privileged account | |
| 33 | 2. Our local Gitblit is configured for create-on-push | |
| 34 | 3. Our local Gitblit is configured for the *BranchTicketService* | |
| 35 | ||
| 36 | **Procedure** | |
| 37 | ||
| 38 | 1. First we'll clone a mirror of the source repository:<pre>git clone --mirror https://dev.gitblit.com/r/gitblit.git </pre> | |
| 39 | 2. Then we'll add a remote for our local Gitblit instance:<pre>cd gitblit.git<br/>git remote add local https://localhost:8443/gitblit.git </pre> | |
| 40 | 3. Then we'll push *everything* to our local Gitblit:<pre>git push --mirror local</pre> | |
| 41 | ||
| 42 | If your push was successful you should have a new repository with the entire official Gitblit tickets data. | |
| 43 | ||
| c134a0 | 44 | ##### Mirroring refs/meta/gitblit/tickets |
| 148b40 | 45 | |
| JM | 46 | Gitblit 1.4.0 introduces a mirroring service. This is not the same as the federation feature - although there are similarities. |
| 47 | ||
| 48 | If you setup a mirror of another Gitblit repository which uses the *BranchTicketService* **AND** your Gitblit instance is configured for *BranchTicketService*, then your Gitblit will automatically fetch and reindex all tickets without intervention or further configuration. | |
| 49 | ||
| 50 | **Things to note about mirrors...** | |
| 51 | ||
| 52 | 1. You must set *git.enableMirroring=true* and optionally change *git.mirrorPeriod* | |
| 53 | 2. Mirrors are read-only. You can not push to a mirror. You can not manipulate a mirror's ticket data. | |
| 54 | 3. Mirrors are a Git feature - not a Gitblit invention. To create one you must currently use Git within your *git.repositoriesFolder*, you must reset your cache, and you must trigger a ticket reindex.<pre>git clone --mirror <url><br/>curl --insecure --user admin:admin "https://localhost:8443/rpc?req=clear_repository_cache"<br/>curl --insecure --user admin:admin "https://localhost:8443/rpc?req=reindex_tickets&name=<repo>"</pre> | |
| 55 | 4. After you have indexed the repository, Gitblit will take over and incrementally update your tickets data on each fetch. | |
| 56 | ||
| 57 | #### Advanced Administration | |
| c134a0 | 58 | Repository owners or Gitblit administrators have the option of manually editing ticket data. To do this you must fetch and checkout the `refs/meta/gitblit/tickets` ref. This orphan branch is where ticket data is stored. You may then use a text editor to **carefully** manipulate journals and push your changes back upstream. I recommend using a JSON validation tool to ensure your changes are valid JSON. |
| 148b40 | 59 | |
| c134a0 | 60 | git fetch origin refs/meta/gitblit/tickets |
| 148b40 | 61 | git checkout -B tix FETCH_HEAD |
| JM | 62 | ...fix data... |
| 63 | git add . | |
| 64 | git commit | |
| c134a0 | 65 | git push origin HEAD:refs/meta/gitblit/tickets |
| 148b40 | 66 | |
| c134a0 | 67 | Gitblit will identify the incoming `refs/meta/gitblit/tickets` ref update and will incrementally index the changed tickets OR, if the update is non-fast-forward, all tickets on that branch will be reindexed. |
| 148b40 | 68 | |
| JM | 69 | ### RedisTicketService |
| 70 | ||
| 71 | #### Ticket Replication | |
| 72 | Redis is capable of sophisticated replication and clustering. I have not configured Redis replication myself. If this topic interests you please document your procedure and open a pull request to improve this section for others who may also be interested in Redis replication. | |
| 73 | ||
| 74 | #### Advanced Administration | |
| 75 | You can directly manipulate the journals in Redis. The most convenient way do manipulate data is using the simple, but very competent, [RedisDesktopManager](http://redisdesktop.com). It even provides JSON pretty printing which faciliates editing. | |
| 76 | ||
| 77 | After you've done this, you will need to reset Gitblit's internal ticket cache and you may need to reindex the tickets, depending on your changes. | |
| 78 | ||
| 79 | The schema of the Redis backend looks like this *repository:object:id*. | |
| 80 | ||
| 81 | redis 127.0.0.1:6379> keys * | |
| 82 | 1) "~james/mytickets.git:ticket:8" | |
| 83 | 2) "~james/mytickets.git:journal:8" | |
| 84 | 3) "~james/mytickets.git:ticket:4" | |
| 85 | 4) "~james/mytickets.git:counter" | |
| 86 | 5) "~james/mytickets.git:journal:2" | |
| 87 | 6) "~james/mytickets.git:journal:4" | |
| 88 | 7) "~james/mytickets.git:journal:7" | |
| 89 | 8) "~james/mytickets.git:ticket:3" | |
| 90 | 9) "~james/mytickets.git:ticket:6" | |
| 91 | 10) "~james/mytickets.git:journal:1" | |
| 92 | 11) "~james/mytickets.git:ticket:2" | |
| 93 | 12) "~james/mytickets.git:journal:6" | |
| 94 | 13) "~james/mytickets.git:ticket:7" | |
| 95 | 14) "~james/mytickets.git:ticket:1" | |
| 96 | 15) "~james/mytickets.git:journal:3" | |
| 97 | ||
| 98 | **Some notes about the Redis backend** | |
| 99 | The *ticket* object keys are provided as a convenience for integration with other systems. Gitblit does not read those keys, but it does update them. | |
| 100 | ||
| 101 | The *journal* object keys are the important ones. Gitblit maintains ticket change journals. The *journal* object keys are Redis LISTs where each list entry is a JSON change document. | |
| 102 | ||
| 103 | The other important object key is the *counter* which is used to assign ticket ids. | |
| 104 | ||
| 105 | ### Resetting the Tickets Cache and Reindexing Tickets | |
| 106 | ||
| 107 | Reindexing can be memory exhaustive. It obviously depends on the number of tickets you have. Normally, you won't need to manually reindex but if you do, offline reindexing is recommended. | |
| 108 | ||
| 109 | #### Offline Reindexing | |
| 110 | ||
| 111 | ##### Gitblit GO | |
| 112 | ||
| 113 | Gitblit GO ships with a script that executes the *com.gitblit.ReindexTickets* tool included in the Gitblit jar file. This tool will reindex *all* tickets in *all* repositories **AND** must be run when Gitblit is offline. | |
| 114 | ||
| 115 | reindex-tickets <baseFolder> | |
| 116 | ||
| 117 | ##### Gitblit WAR/Express | |
| 118 | ||
| 119 | Gitblit WAR/Express does not ship with anything other than the WAR, but you can still reindex tickets offline with a little extra effort. | |
| 120 | ||
| 121 | *Windows* | |
| 122 | ||
| 123 | java -cp "C:/path/to/WEB-INF/lib/*" com.gitblit.ReindexTickets --baseFolder <baseFolder> | |
| 124 | ||
| 125 | *Linux/Unix/Mac OSX* | |
| 126 | ||
| 127 | java -cp /path/to/WEB-INF/lib/* com.gitblit.ReindexTickets --baseFolder <baseFolder> | |
| 128 | ||
| 129 | #### Live Reindexing | |
| 130 | ||
| 131 | You can trigger a live reindex of tickets for any backend using Gitblit's RPC interface and curl or your browser. This will also reset Gitblit's internal ticket cache. Use of this RPC requires *web.enableRpcServlet=true* and *web.enableRpcManagement=true* along with administrator credentials. | |
| 132 | ||
| 133 | curl --insecure --user admin:admin "https://localhost:8443/rpc?req=reindex_tickets" | |
| 134 | curl --insecure --user admin:admin "https://localhost:8443/rpc?req=reindex_tickets&name=gitblit.git" | |
| 135 | ||
| 4d81c9 | 136 | #### Migrating Tickets between Ticket Services |
| JM | 137 | |
| 138 | ##### Gitblit GO | |
| 139 | ||
| 140 | Gitblit GO ships with a script that executes the *com.gitblit.MigrateTickets* tool included in the Gitblit jar file. This tool will migrate *all* tickets in *all* repositories **AND** must be run when Gitblit is offline. | |
| 141 | ||
| 142 | migrate-tickets <outputservice> <baseFolder> | |
| 143 | ||
| 144 | For example, this would migrate tickets from the current ticket service configured in `c:\gitblit-data\gitblit.properties` to a Redis ticket service. The Redis service is configured in the same config file so you must be sure to properly setup all appropriate Redis settings. | |
| 145 | ||
| 146 | migrate-tickets com.gitblit.tickets.RedisTicketService c:\gitblit-data | |
| 147 | ||
| a5086d | 148 | ##### Gitblit WAR |
| 4d81c9 | 149 | |
| a5086d | 150 | Gitblit WAR does not ship with anything other than the WAR, but you can still migrate tickets offline with a little extra effort. |
| 4d81c9 | 151 | |
| JM | 152 | *Windows* |
| 153 | ||
| 154 | java -cp "C:/path/to/WEB-INF/lib/*" com.gitblit.MigrateTickets <outputservice> --baseFolder <baseFolder> | |
| 155 | ||
| 156 | *Linux/Unix/Mac OSX* | |
| 157 | ||
| 158 | java -cp /path/to/WEB-INF/lib/* com.gitblit.MigrateTickets <outputservice> --baseFolder <baseFolder> | |
| 159 | ||
