engineering/unrhodecode
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

project: added all source files and assets

Browse source
This commit is contained in:
Marcin Kuzminski 2016-05-24 15:56:53 +02:00
parent a059b651ea
commit 9a0d8c0b77
1365 changed files with 696516 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

66
docs/tutorials/api-examples.rst Normal file
View file

@ -0,0 +1,66 @@
.. _api-ex:
API Example Usage
=================
Use the following example uses of the |RCE| API to carry out work on your
instances, or |repo| maintanence on the server. For the complete API
documentation, see the :ref:`api` section.
.. _api-strip:
Stripping Commits
-----------------
The strip command is useful for removing commits on the server, allowing
you to push changes without using force. To strip commits on the server, use
the following steps:
1. Install |RCT|, as explained in the :ref:`install-tools` section.
2. Configure the :file:`~/.rhoderc` file with the API connection details, as
explained in the :ref:`config-rhoderc` section.
3. Check the |RCE| changelog and see from which revision onwards you wish to
strip commits. This will also strip all descendants.
.. image:: ../images/pre-strip.png
4. Enter your |RCT| virtual environment, using the following example:
.. code-block:: bash
$ . venv/bin/activate
(venv)$
5. Use the API to strip a commit, or number of commits from a |repo|. In this
example I am stripping the top two commits from ``ad1e0523a4ab`` onwards.
.. note::
Repositories in |repo| groups require the |repo| group to be passed as
part of the ``repoid``.
.. code-block:: bash
# Run the Strip API call
$ rhodecode-api --instance-name=instance-id strip \
repoid:repo-group/repo-name revision:ad1e0523a4ab branch:stable
# Check the JSON-RPC verification
.. code-block:: jsonld
{
"error": null,
"id": 5960,
"result": {
"msg": "Stripped commit ad1e0523a4ab from
repo `repo-group/repo-name`",
"repository": "repo-group/repo-name"
}
}
6. Once the commits are stripped, you can verify that they are
stripped on the web interface.
.. image:: ../images/post-strip.png

103
docs/tutorials/appenlight-setup.rst Normal file
View file

@ -0,0 +1,103 @@
How To Use |AE| to Monitor |RCE|
================================
* For cloud based monitoring using |AE|, `sign up for an account`_ first and
get your user details.
* For self hosted monitoring, you'll need to download and setup |AE| first.
Contact support@rhodecode.com for more details.
|AE| Side Of The Setup
----------------------
- From the interface, create an application for |AE| to monitor:
:menuselection:`Settings --> Create Application`
- Add in your |RCE| instance details.
- Take note of the Public and Private API keys on the application page. You
will need to add the private key to your |RCE| configuration file.
For more information, see the the |AE| documentation `here`_.
|RCE| Side Of The Setup
-----------------------
Once you have your |AE| account details, configure the |RCE|
:file:`home/{user}/.rccontrol/{instance-id}/rhodecode.ini` file with the
following details to set up the connection between the two systems.
.. tip::
The section below should already be present in your configuration file if
running a recent version of |RCE|.
* Enable the |AE| connection by setting ``appenlight = true``.
* Set your |AE| URL using the ``appenlight.server_url = URL`` option.
* Set your |AE| |authtoken| using the ``appenlight.api_key = TOKEN`` option.
.. code-block:: ini
:emphasize-lines: 10,12,13
###################################
## ERROR AND LOG HANDLING SYSTEM ##
###################################
## Appenlight is tailored to work with RhodeCode, see
## http://appenlight.com for details how to obtain an account
## you must install python package `appenlight_client` to make it work
## appenlight enabled
appenlight = false
appenlight.server_url = https://api.appenlight.com
appenlight.api_key = YOUR_PRIVATE_API_KEY
## TWEAK AMOUNT OF INFO SENT HERE
## enables 404 error logging (default False)
appenlight.report_404 = false
## time in seconds after request is considered being slow (default 1)
appenlight.slow_request_time = 1
## record slow requests in application
## (needs to be enabled for slow datastore recording and time tracking)
appenlight.slow_requests = true
## enable hooking to application loggers
appenlight.logging = true
## minimum log level for log capture
appenlight.logging.level = WARNING
## send logs only from erroneous/slow requests
## (saves API quota for intensive logging)
appenlight.logging_on_error = false
## list of additonal keywords that should be grabbed from environ object
## can be string with comma separated list of words in lowercase
## (by default client will always send following info:
## 'REMOTE_USER', 'REMOTE_ADDR', 'SERVER_NAME', 'CONTENT_TYPE' + all keys that
## start with HTTP* this list be extended with additional keywords here
appenlight.environ_keys_whitelist = ""
## list of keywords that should be blanked from request object
## can be string with comma separated list of words in lowercase
## (by default client will always blank keys that contain following words
## 'password', 'passwd', 'pwd', 'auth_tkt', 'secret', 'csrf'
## this list be extended with additional keywords set here
appenlight.request_keys_blacklist = ""
## list of namespaces that should be ignores when gathering log entries
## can be string with comma separated list of namespaces
## (by default the client ignores own entries: appenlight_client.client)
appenlight.log_namespace_blacklist = ""
Verifying The Setup
-------------------
Once |RCE| and |AE| are working together you will see the monitoring begin on
your |AE| dashboard when you start carrying out actions in |RCE|.
.. image:: ../images/ae-verify.png
.. _sign up for an account: https://appenlight.rhodecode.com/
.. _here: https://appenlight.rhodecode.com/page/api/main

41
docs/tutorials/branching-vs-bookmarking.rst Normal file
View file

@ -0,0 +1,41 @@
.. _bvb:
|hg| Branching Vs Bookmarking
=============================
If you wish to use the branching workflow in |hg|, as mentioned in the
:ref:`workflow` section, then there is a subtle but important difference to
note between what branching means in |git| and |hg|.
* |hg| stores branch information as a permanent part of each commit. Each
branch needs to be named and is assigned persistent symbolic links inside the
|repo|.
* In |git|, by contrast, a branch is simply a lightweight movable pointer to
a commit.
This is where bookmarks replicate the |git| branch functionality in |hg|. A
bookmark is a references to a commit that can be automatically updated when
new commits are made. For more information, see the `Mercurial Bookmark`_
documentation.
To use |hg| bookmarks like |git| branches, see the following example.
.. code-block:: bash
# Make a bookmark particular revision
$ hg bookmark -r 3400 my-bookmark
# push the bookmark to the server
$ hg push -B my-bookmark
# Delete remote bookmark, by deleting locally, then push deletion
$ hg bookmark -d my-bookmark
$ hg push -B my-bookmark
To open a |pr| from a bookmark using |RCE|, use the usual |pr| steps.
.. image:: ../images/pr-from-bookmark.png
.. _Mercurial Bookmark: https://mercurial.selenic.com/wiki/Bookmarks

220
docs/tutorials/deploy-from-host.rst Normal file
View file

@ -0,0 +1,220 @@
.. _hosted-solution:
Deploy |RCE| From a Hosted Server
=================================
If you wish to deploy your own |RCE| instance from something like a
`Digital Ocean`_ droplet, or a `hetzner`_ server use the following
instructions to get it setup.
I'm using an Ubuntu 14.04 image for the purposes of this
tutorial, but all other Unix environments will be pretty similar. You can
check out the full lists of supported platforms and versions in the
:ref:`system-overview-ref` section.
Create a Digital Ocean Droplet
------------------------------
1. Sign into Digital Ocean.
2. Create a Droplet choosing Ubuntu 14.04 as your |os|.
3. (Optional) Add SSH keys if you have them set up.
Configure Your Server
---------------------
Once you have your server created, you need to sign into it and set it up to
host |RCE|.
1. Open a terminal and sign into your server. Digital Ocean will mail you the
IP address. You'll need to change your password on the first login if you
don not have SSH keys set up.
.. code-block:: bash
$ ssh root@203.0.113.113
2. It is not advised to install |RCE| as the ``root`` user. So create a user
with sudo permissions and then carry out the rest of the steps from that user
account.
.. code-block:: bash
# Create a user with sudo permissions
root@rhodecode:~# sudo useradd -m -s /bin/bash -d /home/brian -U brian
root@rhodecode:~# sudo usermod -a -G sudo brian
# Set the password for that user
root@rhodecode:~# passwd brian
Enter new UNIX password:
Retype new UNIX password:
passwd: password updated successfully
# Switch to that user for the rest of the steps
root@rhodecode:~# su brian
# You should see your home dir change to what was set during installation
brian@rhodecode:~$ cd ~
brian@rhodecode:~$ pwd
/home/brian
Once you have this set up, you are ready to install |RCC|.
Install |RCC|
-------------
|RCC| will install and manage the package dependencies for your |RCE| instance.
1. Download the |RCC| installer from https://rhodecode.com/download/
2. Once downloaded to your computer, transfer the package to your server
.. note::
These steps happen on your computer, not on the server.
.. code-block:: bash
# Change to where the file is downloaded
$ cd Downloads/
# SFTP to your server
$ sftp brian@203.0.113.113
# Use mput to transfer the file
sftp> mput RhodeCode-installer-linux-391_b1a804c4d69b_d6c087d520e3
Uploading RhodeCode-installer-linux-391_b1a804c4d69b_d6c087d520e3 to /home/brian/RhodeCode-installer-linux-391_b1a804c4d69b_d6c087d520e3
RhodeCode-installer-linux-391_b1a804c4d69b_d6c087d 100% 289MB 4.1MB/s 01:11
sftp> exit
The |RCC| installer is now on your server, and you can read the full
instructions here
:ref:`Install RhodeCode Control <control:rcc-install-ref>`,
but below is the example shortcut.
.. code-block:: bash
# Check that the script is uploaded to your home directory
$ ls -1
RhodeCode-installer-linux-391_b1a804c4d69b_d6c087d520e3
# Change the script permissions
$ chmod 755 RhodeCode-installer-linux*
# Run the installer and accept the prompts
$ ./RhodeCode-installer-linux-*
.. important::
Once finished, exit the terminal and sign in again. This is to refresh you
session to pick up the new commands.
Install |RCE|
-------------
Now that |RCC| is installed, you can install |RCE|. For the full
instructions, see
:ref:`Install RhodeCode Enterprise <control:rce-cli-install-ref>`,
but the below is an example shortcut.
.. code-block:: bash
# Install a VCS Server and follow the prompts
$ rccontrol install VCSServer --start-at-boot
Extracting VCSServer ...
Configuring RhodeCode VCS Server ...
Supervisord state is: RUNNING
Added process group vcsserver-1
# Install a RhodeCode Enterprise instance and follow the prompts
$ rccontrol install Enterprise --start-at-boot
Configuration of RhodeCode Enterprise passed.
Supervisord state is: RUNNING
Added process group enterprise-1
|RCE| is now installed on your server, and is running on the port displayed
by the ``rccontrol status`` command.
.. code-block:: bash
brian@rhodecode:~$ rccontrol status
- NAME: enterprise-1
- STATUS: RUNNING
- TYPE: Enterprise
- VERSION: 3.1.1
- URL: http://127.0.0.1:10002
- NAME: vcsserver-1
- STATUS: RUNNING
- TYPE: VCSServer
- VERSION: 1.1.1
- URL: http://127.0.0.1:10001
Serve |RCE| using Nginx
-----------------------
Now that |RCE| is running, you need to use Nginx or Apache to serve it to
users. For detailed instructions about setting up your webserver, see the
:ref:`rhodecode-admin-ref` section. But the below shortcut should help serve
it.
1. Install Nginx on your server.
.. code-block:: bash
# Install nginx
$ sudo apt-get install nginx
2. Create a virtual hosts file for RhodeCode Enterprise. Create
the file in this location :file:`/etc/nginx/sites-available`. In this demo
I have called it ``vcs.conf``
.. code-block:: bash
# Create the file
$ sudo vi /etc/nginx/sites-available/vcs.conf
Use the following example to create yours.
.. code-block:: nginx
server {
listen 80;
# Change to your IP, or a domain name if you've set that up
server_name 203.0.113.113 ;
location / {
# Set this line to match the RhodeCode Enterprise Instance URL
proxy_pass http://127.0.0.1:10002/;
proxy_set_header Host $Host;
proxy_buffering off;
# Setting this to a high number allows large repo pushes
client_max_body_size 4G;
}
}
3. Symlink the virtual hosts file to the ``sites-enabled`` folder,
and then restart Nginx.
.. code-block:: bash
# Symlink the virtual hosts file
$ ln -s /etc/nginx/sites-available/vcs.conf /etc/nginx/sites-enabled/vcs.conf
# You can also delete the Nginx default symlink
$ rm /etc/nginx/sites-enabled/default
# Restart Nginx
$ sudo /etc/init.d/nginx restart
* Restarting nginx nginx [ OK ]
Once restarted, you should see a clean |RCE| instance running on the IP
address, or the domain you have set up.
.. image:: ../images/clean-rce.png
:alt: A fresh RhodeCode Enterprise Instance
.. _Digital Ocean: https://www.digitalocean.com/
.. _hetzner: https://www.hetzner.de/en/

5
docs/tutorials/docs-build.rst Normal file
View file

@ -0,0 +1,5 @@
Setting up docs deploy
======================
* some
* list

62
docs/tutorials/dvcs-best-practices.rst Normal file
View file

@ -0,0 +1,62 @@
.. _vcs-bps:
Collaboration Best Practices
============================
This section outlines some of the best practices when working with
Distributed Version Control Systems (DVCS). These best practices will help
you get the most out |git| and |hg| when working with others.
Test Locally
------------
As most test suites are also included in the |repo|, it is good practice to
ensure your changes are passing locally before opening a pull request and
having the CI server run the tests for you. The two main benefits here are:
* Not clogging up the test machine with untested and thus more likely to fail
test runs.
* Only opening |prs| that are passing locally increases the quality of
feedback at the peer review stage as reviewers can focus on high
quality feedback.
Agree on Workflow
-----------------
When working with others, one of the first things to agree upon is a workflow.
This agreement means that everyone knows what is happening at a particular
stage of the collaboration cycle and that they can deliver in accordance with
the expectations.
Keep Commits To One Task
------------------------
When committing it is good practice to keep each commit to a specific task.
This allows the |repo| admin to easily cherry pick or graft work between
branches should there be a need to do so for particular release processes. It
also makes it easy for colleagues to understand the changes going into a
|repo|.
Use Descriptive Commit Messages
-------------------------------
When writing commit messages, it is good practice to contextualise the
message by prepending a label which will give the reader a clue about what
area the changes apply to, and to then write a brief but descriptive message
that explains in more detail.
.. code-block:: bash
o 10739:0fdd6cd2b97a [default] - public
| 2 days ago by Johannes Bornhold | B:,T:
| ac-tests: Change browser.click to be only locator based
Master Your Tools
-----------------
The best way to get good at something it to break it and fix it. One
advantage of DVCS is how cheap forking and branching is. One tip is to create
your own fork and master branching, rebasing, cherry picking, merging, or any
other skill you currently find challenging. Once you have mastered it on the
disposable branch or fork you can carry out tasks on your main |repos| with
confidence.

39
docs/tutorials/hg-large-ext.rst Normal file
View file

@ -0,0 +1,39 @@
.. _hg-big-files:
|hg| Large Files Extension
==========================
Large files, such as image or zip files can cause a lot of bandwidth overhead
during clone, push, and pull operations. To remove this inefficiency, |hg|
has a large files extension which tracks their revisions by checksums. This
means that the large files are only downloaded when they are needed as part
of the current revision. This saves both disk space and bandwidth.
To find out more, see the |hg| `Large Files Extensions Documentation`_.
To configure the large files extension, you need to set up your
:file:`~/.hgrc` file.
1. Open your :file:`~/.hgrc` file.
2. Add ``largefiles =`` to the ``[extensions]`` section.
3. Configure the ``[largefiles]`` section with the patterns and file size you
wish |hg| to handle as large. The ``minsize`` option is specified in
megabytes.
4. Save your changes.
.. code-block:: ini
[extensions]
hgext.churn =
largefiles =
rebase =
record =
histedit =
[largefiles]
patterns = re:.*\.(png|bmp|jpg|zip|tar|tar.gz|rar)$
minsize = 10
For a complete :file:`~/.hgrc` file example, see :ref:`config-hgrc`.
.. _Large Files Extensions Documentation: http://mercurial.selenic.com/wiki/LargefilesExtension

111
docs/tutorials/merging.rst Normal file
View file

@ -0,0 +1,111 @@
.. _merging:
Merging in |hg|
===============
Sometimes you will need to fix conflicts when merging files. In |hg| there
are a number of different options which you can use for handling merging, and
you can set your preferred one in the :file:`~/.hgrc` file. The options fall
into two categories *internal merging* or *tool merging*.
Internal merging marks the files with the ``<<<<<``,
``>>>>>``, and ``=======`` symbols denoting the position of the conflict
in the file and you resolve the changes on your terminal. The following
example sets `Meld`_ as the merge handler.
.. code-block:: ini
[ui]
merge = internal:merge
Tool merging differs slightly depending on the tool you use, but they will
all do the same thing. Highlight the conflict area in some manner, and allow
you to make the necessary changes to resolve the conflicts. Set a merge tool
using the following example.
.. code-block:: ini
[merge-tools]
meld3.executable = /usr/local/bin/meld
For more detailed information, see the :ref:`basic-vcs-cmds` section, or the
`Mercurial merge-tools`_ documentation. Use the following example steps to
handle merging conflicts.
1. Check the list of conflicts on the command line, in this example
you can see the list as the ``default`` and ``stable`` branches are in the
process of being merged.
.. code-block:: bash
:emphasize-lines: 10-12,16-17,20-21
$ hg branch
stable
$ hg merge default
note: using 4480fbc4562c as ancestor of 7c9a8dfb9dd6 and fbefb727a452
alternatively, use --config merge.preferancestor=a1e8bd6df0ce
merging default.nix
merging docs-internal/changelog.rst
merging rhodecode/VERSION
merging rhodecode/controllers/api/utils.py
warning: conflicts during merge.
merging rhodecode/controllers/api/utils.py incomplete!
(edit conflicts, then use 'hg resolve --mark')
merging rhodecode/lib/diffs.py
merging rhodecode/model/scm.py
merging rhodecode/tests/api/test_utils.py
warning: conflicts during merge.
merging rhodecode/tests/api/test_utils.py incomplete!
(edit conflicts, then use 'hg resolve --mark')
merging rhodecode/tests/models/test_scm.py
warning: conflicts during merge.
merging rhodecode/tests/models/test_scm.py incomplete!
(edit conflicts, then use 'hg resolve --mark')
merging vcsserver/default.nix
merging vcsserver/vcsserver/VERSION
42 files updated, 7 files merged, 2 files removed, 3 files unresolved
use 'hg resolve' to retry unresolved file merges or 'hg update -C .' to abandon
2. Open each of the highlighted files, and fix the conflicts in each. Each merge
conflict will look something like the following example, with the ``<<<<<``,
``>>>>>``, and ``=======`` symbols denoting the position of the conflict
in the file. You need to fix the content so that it is correct.
.. code-block:: python
# Change this example conflict
def pre_request(worker, req):
<<<<<<<<<<<<<<
worker.log.debug("[%s] PRE WORKER: %s" %(worker.pid, req.method))
===============
worker.log.debug("[%s] PRE WORKER: %s %s" % (worker.pid, req.method,
req.path))
>>>>>>>>>>>>>>
# To this working code
def pre_request(worker, req):
worker.log.debug("[%s] PRE WORKER: %s %s" % (worker.pid, req.method,
req.path))
3. Once you have finished fixing the conflicts, you need to mark them as
resolved, and then commit the changes.
.. code-block:: bash
# Mark the merges as resolved
$ hg resolve --mark
# Commit the changes
$ hg commit -m "merge commit message"
5. Once you have finished your merge, if the the original |repo| history on
the server is different you have two options:
* Push with force using ``hg push --force`` which will create a new head.
* Strip your commits on the server back to a previous revision, and then push
the new history. To strip commits on the server, see the ``strip``
information in the :ref:`api` documentation.
.. _Mercurial merge-tools: https://mercurial.selenic.com/wiki/MergeToolConfiguration
.. _Meld: http://meldmerge.org/

91
docs/tutorials/multi-instance-setup.rst Normal file
View file

@ -0,0 +1,91 @@
.. _multi-instance-setup:
Scaling |RCE| Using Multiple Instances
======================================
Running multiple instances of |RCE| from a single database can be used to
scale the application for the following deployment setups:
* Using dedicated Continuous Integrations instances.
* Locating instances closer to geographically dispersed development teams.
* Running production and testing instances, or failover instances on a
different server.
* Running proxy read-only instances for pull operations.
If you wish to run multiple instances of |RCE| using a single database for
settings, use the following instructions to set this up. Before you get onto
multiple instances though, you should install |RCE|, and set
up your first instance as you see fit. You can see the full instructions here
:ref:`Installing RhodeCode Enterprise <control:rcc>`
Once you have configured your first instance, you can run additional instances
from the same database using the following steps:
1. Install a new instance of |RCE|, choosing SQLite as the database. It is
important to choose SQLite, because this will not overwrite any other
database settings you may have.
Once the new instance is installed you need to update the licence token and
database connection string in the
:file:`/home/{user}/.rccontrol/{instance-id}/rhodecode.ini` file.
.. code-block:: bash
$ rccontrol install Enterprise
Agree to the licence agreement? [y/N]: y
Username [admin]: username
Password (min 6 chars):
Repeat for confirmation:
Email: user@example.com
Respositories location [/home/brian/repos]:
IP to start the Enterprise server on [127.0.0.1]:
Port for the Enterprise server to use [10000]:
Database type - [s]qlite, [m]ysql, [p]ostresql: s
2. The licence token used on each new instance needs to be the token from your
initial instance. This allows multiple instances to run the same licence key.
To get the licence token, go to the |RCE| interface of your primary
instance and select :menuselection:`admin --> setting --> license`. Then
update the licence token setting in each new instance's
:file:`rhodecode.ini` file.
.. code-block:: ini
## generated license token, goto license page in RhodeCode settings to get
## new token
license_token = add-token-here
3. Update the database connection string in the
:file:`rhodecode.ini` file to point to your database. For
more information, see :ref:`config-database`.
.. code-block:: ini
#########################################################
### DB CONFIGS - EACH DB WILL HAVE IT'S OWN CONFIG ###
#########################################################
# Default SQLite config
sqlalchemy.db1.url = sqlite:////home/user/.rccontrol/enterprise-1/rhodecode.db
# Use this example for a PostgreSQL
sqlalchemy.db1.url = postgresql://username:password@localhost/rhodecode
4. Restart your updated instance. Once restarted the new instance will read
the licence key in the database and will function identically as the
original instance.
.. code-block:: bash
$ rccontrol restart enterprise-2
If you wish to add additional performance to your setup, see the
:ref:`rhodecode-tuning-ref` section.
Scaling Deployment Diagram
--------------------------
.. image:: ../images/scaling-diagrm.png
:align: center

54
docs/tutorials/rebase-commits-git.rst Normal file
View file

@ -0,0 +1,54 @@
.. _rebase-rebase-git:
How to Rebase in |git|
======================
Rebasing can take two form in |git|.
* Rebasing changes when you pull from upstream
* Rebasing one branch on top of another
If you need to understand more about branching, and the terminology, see the
:ref:`branch-wf` section.
Rebasing When Pulling from Upstream
-----------------------------------
This will pull any changes from the remote server, and rebase the changes on
your local branch on top of them.
.. code-block:: bash
# Move to the branch you wish to rebase
$ git checkout branchname
# Pull changes on master and rebase on top of latest changes
$ git pull --rebase upstream master
# Push the rebase to origin
$ git push -f origin branchname
Rebasing Branches
-----------------
Rebasing branches in |git| means that you take one branch and rebase the work
on that branch on top of another. In the following example, the
``triple`` branch will be rebased on top of the ``second-pass`` branch.
1. List the available branches in your |repo|.
.. code-block:: bash
$ git branch
first-pass
* master
second-pass
triple
2. Rebase the ``triple`` on top of the ``second-pass`` branch.
.. code-block:: bash
$ git rebase second-pass triple
First, rewinding head to replay your work on top of it...
Fast-forwarded triple to second-pass.

118
docs/tutorials/rebase-commits.rst Normal file
View file

@ -0,0 +1,118 @@
.. _rebase-rebase:
How to Rebase in |hg|
=====================
To rebase in |hg| you will need the ``rebase`` extensions enabled in your
:file:`~/.hgrc` file. Use the following example, or for more detailed
information see the :ref:`config-hgrc` section.
.. code-block:: ini
[extensions]
rebase =
Rebasing in |hg|
----------------
Occasionally you may have to rebase commits if you have created a new head on
your fork. In short, rebasing mean taking one commit and moving a commit, or
set of commits, from a different head on top of it. To do this, use the
following example:
1. Check your on the right branch, and move to the correct one if needed.
.. code-block:: bash
# Display which branch you are on
$ hg branch
default
# Move to the stable branch
$ hg update stable
2. Look at your graphlog, and decide what commits need to be rebased. In this
case, I want to rebase 1206 and 1207 on top of 1226. Note how these are
already in a public state as I have already pushed to my fork.
.. code-block:: bash
:emphasize-lines: 1,13,17
| o 1226:1046ed30734d [stable] - public
| | 3 days ago by Oliver Strobel | B:,T:
| | enterprise: catch failure to create repo_dir
| |
| o 1225:7aba10b8ee97 [stable] - public
| | 3 days ago by Oliver Strobel | B:,T:
| | control: bump version to 1.1.9
| |
o | 1208:0ef7c9d4c1cc [default] - public
| | 2 weeks ago by Oliver Strobel | B:,T:
| | Added tag 1.1.7 for changeset 3acf64b88845
| |
| | @ 1207:39562e195e34 [stable] - public
| | | 3 weeks ago by Brian | B:,T:
| | | docs: note added to *rccontrol install* regarding overwriting DB
| | |
| | o 1206:39562e195e34 [stable] - public
| |/ 3 weeks ago by Brian | B:,T:
| | docs: update command line install example
3. To do this use the following example.
* Draft the commits back to the source revision.
* ``-s`` is the source, essentially what you are rebasing.
* ``-d`` is the destination, which is where you are putting it.
Rebasing the source commit will automatically rebase its descendants. In this
example I am using ``--force`` to draft commits already pushed to my fork.
Doing this is not best practices on a main |repo|.
.. code-block:: bash
# Put the commits into draft status
# This will draft all subsequent commits on the relevant branch
hg phase --draft --force -r 1206
# Rebase 1206 on top of 1226
$ hg rebase -s 1206 -d 1226
saved backup bundle to /repo-fork/.hg/strip-backup/39562e195e34-backup.hg
4. Once you have rebased the commits, check them on the graphlog
.. code-block:: bash
:emphasize-lines: 1,5,9
o 1233:707ef1590e71 [stable] - draft
| 3 weeks ago by Brian | B:,T:tip
| docs: note added to *rccontrol install* regarding overwriting DB
|
o 1232:707ef1590e71 [stable] - draft
| 3 weeks ago by Brian | B:,T:tip
| docs: update command line install example
|
@ | 1225:1046ed30734d [stable] - draft
| | 3 days ago by Oliver Strobel | B:,T:
| | enterprise: catch failure to create repo_dir
5. Once you have finished your rebase, if the the original |repo| history on
the server is different you have two options:
* Push the specific revisions using ``hg push -r <revision>``, or push all
with force using ``hg push --force`` which will create a new head.
* Strip your commits on the server back to a previous revision, and then push
the new history. To strip commits on the server, see the ``strip``
information in the :ref:`api` documentation.
.. important::
As with all examples, this one is rather straight forward but rebasing can
become a complicated affair if you need to fix merges and conflicts
during the rebase. For more detailed rebasing information, see the
`Mercurial Rebase`_ page which has more detailed instructions for various
scenarios.
.. _Mercurial Rebase: https://mercurial.selenic.com/wiki/RebaseExtension
.. _Mercurial Phases: https://mercurial.selenic.com/wiki/Phases

61
docs/tutorials/scaling-best-practices.rst Normal file
View file

@ -0,0 +1,61 @@
.. _scaling-tips:
======================
Scaling Best Practices
======================
When deploying |RCE| at scale; 100s of users, multiple instances, CI servers,
there are a number of steps you can take to ensure you are getting the
most out of your system.
Separate Users and CI Servers
-----------------------------
You can configure multiple |RCE| instances to point to the same database and
set of |repos|. This lets users work on an instance that has less traffic
than those being hit by CI servers. To configure this, use |RCC| to install
multiple instances and configure the database and |repos| connection. If you
do need to reset the database connection, see the
:ref:`config-database` section.
Once configured, set your CI servers to use a particular instance and for
user specific instances you can configure loads balancing. See the
:ref:`nginx-ws-ref` section for examples.
Switch to Database Sessions
---------------------------
To increase database performance switch to database-based user sessions. In a
large scale deployment, we recommend switching from file-based
sessions to database-based user sessions. For configuration details, see the
:ref:`db-session-ref` section.
Tuning |RCE|
------------
There are also a number of options available to tune |RCE| for certain
scenarios, including memory cache size. See the :ref:`rhodecode-tuning-ref`
section.
Use Authentication Tokens
-------------------------
Set up a user account for external services, and then use Authentication
Tokens with those external services. These tokens work with
push/pull operations only, and you can manage multiple tokens through this user
account, and revoke particular ones if necessary. In this way one user can have
multiple tokens, so all your jenkins/CI servers could share one account.
* To enable tokens, go to :menuselection:`Admin --> Authentication` and enable
the `rhodecode.lib.auth_modules.auth_token` library.
* To create tokens, go to
:menuselection:`Username --> My Account --> Auth tokens` and generate the
necessary tokens. For more information, see the :ref:`config-token-ref`
section.
Scaling Deployment Diagram
--------------------------
.. image:: ../images/scaling-diagrm.png
:align: center

62
docs/tutorials/squash-commits-git.rst Normal file
View file

@ -0,0 +1,62 @@
.. _squash-git:
How to Squash Commits in |git|
==============================
To squash commits in |git|, use the following steps.
1. Use ``git log`` to view the commits messages on your branch, and decide
how many you want to squash into one commit.
2. Using the ``rebase`` command, chose the number of commits you wish to
squash. This will then open the list of commits in your default editor
allowing you to chose what to do with each.
.. code-block:: bash
# Squash the last 4 commits
$ git rebase -i HEAD~4
3. When the editor opens, pick the main commit, and the commits you wish
to squash, and then save. This will then open the editor on the
next phase where you can edit the picked commit.
.. code-block:: bash
pick 575447a realign bike handlebars
s 583e99c Add hipster bullhorn handlebars (dont judge me)
s 8829a05 Add initial disc brakes for stopping
s 91322e6 Add BikeEvent administration
# Rebase d839c1a..583e99c onto d839c1a (2 TODO item(s))
#
# Commands:
# p, pick = use commit
# r, reword = use commit, but edit the commit message
# e, edit = use commit, but stop for amending
# s, squash = use commit, but meld into previous commit
# f, fixup = like "squash", but discard this commits log message
# x, exec = run command (the rest of the line) using shell
4. Edit the picked commit to explain the squash in more detail, and then save.
.. code-block:: bash
# This is a combination of 4 commits.
# The first commit's message is:
The full bike setup, with brakes, handlebars, and alignment fixed.
5. Using ``git log``, you should now see your squashed commit message
.. code-block:: bash
$ git log
commit c5424b2619b1a7c01f817279df787660c76081ea
Author: user <user@ubuntu>
Date: Wed Nov 4 19:45:37 2015 +0100
The full bike setup, including handlebars, brakes, and alignment.
6. If you have already push to the remote |repo|, you will need to push your
changes using force, ``git push --force``

125
docs/tutorials/squash-commits.rst Normal file
View file

@ -0,0 +1,125 @@
.. _squash-rebase:
How to Squash Commits in |hg|
=============================
To squash commits in |hg| you will need the ``histedit`` extensions enabled
in your :file:`~/.hgrc` file. Use the following example, or for more detailed
information see the :ref:`config-hgrc` section.
.. code-block:: ini
[extensions]
histedit =
Squashing Commits
-----------------
To squash commits, use the following instructions.
1. Using ``hg log``, or ``hg glog``, check your repository history and
choose the revision upon which you want to squash commits.
2. The commit status needs to be in draft. If necessary, change the commit
status to draft back as far as the chosen revision, using
the following command: ``hg phase --draft --force -r rev-id``. It's not
best practices to use ``--force`` on a main |repo|, but this example is
based on a fork. To learn more about phases, read the `Mercurial Phases`_
docs. See the following example:
.. code-block:: bash
# Put commits into draft status if needed
hg phase --draft --force -r 9039
# Check the changlog to ensure the commits are in draft
@ 9041:c680f30edc60 [default] - draft
| 7 weeks ago by Johannes Bornhold | B:,T:tip
| nix: Add version of transifex-client into default.nix
|
o 9040:66f03981cfcd [default] - draft
| 7 weeks ago by lisaq | B:,T:
| fixes #1592 removing legacy css files
|
o 9039:388db711042f [default] - draft
| 7 weeks ago by Brian | B:,T:
| docs: fixed *doCheck = false* with propogatedbuildinputs fragment
|
o 9038:ef41dce16c12 [default] - public
| 8 weeks ago by Brian | B:,T:
| Docs: updating dependencies for Sphinx 131, but staying at 122 for now
3. Once the commits are in draft, run the ``hg histedit rev-id`` command,
specifying the earliest draft commit. This will open the history edit
function in your terminal, allowing you to fold the commit messages into
one. Select a commit to use as the one into which the others will be
squashed. Then save the file.
.. code-block:: bash
# Run the history edit specifying the base revision
hg histedit 9039
pick 388db711042f 9039 docs: fixed *doCheck = false* with propogatedbuildinputs
fold 66f03981cfcd 9040 fixes #1592 removing legacy css files
fold c680f30edc60 9041 nix: Add version of transifex-client into default.nix
# Edit history between 388db711042f and c680f30edc60
#
# Commits are listed from least to most recent
#
# Commands:
# p, pick = use commit
# e, edit = use commit, but stop for amending
# f, fold = use commit, but combine it with the one above
# d, drop = remove commit from history
# m, mess = edit message without changing commit content
4. Once those settings are saved, the terminal will open up an editor and you
can change the commit message. When finished, save again.
.. code-block:: bash
# add a new commit message or keep the original one
docs: added translations and packaging. Squashed commit.
# adding HG: in front of a line will remove it once saved
HG:docs: added translations and packaging. Squashed commit.
HG:nix: Add version of transifex-client into default.nix
HG:docs: fixed *doCheck = false* with propogatedbuildinputs fragment
5. Your commit messages will now be squashed into a single commit. You will
also get a message about a backup bundle where |hg| will store the history of
the squashed commit.
.. code-block:: bash
3 files updated, 0 files merged, 0 files removed, 0 files unresolved
saved backup bundle to /tutorials-fork/.hg/strip-backup/38b711042f-backup.hg
saved backup bundle to /tutorials-fork/.hg/strip-backup/f19da9449f-backup.hg
6. See the squashed commit message using the ``hg log`` or ``hg glog`` command.
.. code-block:: bash
@ 9039:44e6fc3bf6b5 [default] - draft
| 7 weeks ago by Brian | B:,T:tip
| docs: added translations and packaging. Squashed commit.
|
o 9038:ef41dce16c12 [default] - draft
| 8 weeks ago by Brian | B:,T:
| Docs: updating dependencies for Sphinx 131, but staying at 122
|
o 9037:411a82632f54 [default] - draft
|\ 7 weeks ago by Johannes Bornhold | B:,T:
| | release: Merge back stable into default after release 3.2.1
7. Once you have squashed the commits, to push these changes to the server you
have two options:
* Push with force using ``hg push --force`` which will create a new head.
* Strip your commits on the server back to a previous revision, and then push
the new history. To strip commits on the server, see the ``strip``
information in the :ref:`api` documentation.
.. _Mercurial Phases: https://mercurial.selenic.com/wiki/Phases

26
docs/tutorials/tutorials.rst Normal file
View file

@ -0,0 +1,26 @@
.. _rc-tutorials:
|RCE| Tutorials
===============
The following tutorials are aimed at helping you to deploy |RCE| in various
different ways. If you would like to see a certain scenario documented,
then please send a request to support@rhodecode.com
.. toctree::
:maxdepth: 1
deploy-from-host
hg-large-ext
multi-instance-setup
scaling-best-practices
squash-commits
squash-commits-git
rebase-commits
rebase-commits-git
api-examples
merging
branching-vs-bookmarking
windows-to-linux
dvcs-best-practices
appenlight-setup

121
docs/tutorials/windows-to-linux.rst Normal file
View file

@ -0,0 +1,121 @@
Moving From Windows to Linux
============================
If you are moving from a Windows server to a Linux server, especially from
running an older version of |RCE| pre 2.x, use the following information to
successfully migrate your instances and database.
Overview
--------
* Install |RCC| on your Linux server, use the
:ref:`RhodeCode Control Docs <control:rcc>` to guide you through this.
* Copy your |repos| directory to the Linux server.
* Copy your original :file:`rhodecode.ini` file to the Linux server, named
:file:`production.ini` in older versions, and make a minor edit to
point to the copied database.
* Copy your original instance database and update Windows paths to Linux
paths pointing to your |repos| directory.
* Use |RCC| to import and upgrade your |RCE| instance, using the copied and
edited file and database.
Pre-requisites
--------------
* For MySQL, do not use `localhost` in the database connection string of the
:file:`rhodecode.ini` file.
* InnoDB must be the database tables engine.
* Contact |RC| for a new licence Key/Token pair. If you don't, a trial licence
will be applied so you are not locked out of the upgraded instance.
You can find the specific instructions to carry out these pre-requisite steps
in the :ref:`RhodeCode Control upgrade <control:rce-upgrade-2x>` docs.
Configuration File Update
-------------------------
Configure the copied :file:`rhodecode.ini` file to connect to your copied
database. Use the following steps:
1. Open the copied :file:`rhodecode.ini` file.
2. When you open the file, find the database configuration section,
and use the below example to change the connection details:
.. code-block:: ini
#########################################################
### DB CONFIGS - EACH DB WILL HAVE IT'S OWN CONFIG ###
#########################################################
# Point to copied DB
sqlalchemy.db1.url = postgresql://postgres:qwe@localhost/rhodecode.db.copy
sqlalchemy.db1.url = mysql://root:qweqwe@127.0.0.1/rhodecode.db.copy
Database Update
---------------
Update the Windows paths in the ``rhodecode.rhodecode_ui`` database tables.
To do this log into the database and reset the file paths to
Unix format. One login option is to use iShell, see usage examples in the
:ref:`rhodecode-reset-ref` section.
.. code-block:: python
In [28]: from rhodecode.model.settings import SettingsModel
In [29]: paths = SettingsModel().get_ui_by_section('paths')
In [30]: paths[0].value = '/home/user/repos'
In [32]: Session().add(paths[0])
In [33]: Session().commit()
Import and Upgrade
------------------
Once you have made your changes, use |RCC| to import and upgrade your |RCE|
instance to the latest version.
.. code-block:: bash
# Import original instance as explained above
$ rccontrol import Enterprise path/to/rhodecode.ini
# Install a VCS Server as explained above
$ rccontrol install VCSServer
# Check the status of them
$ rccontrol status
- NAME: enterprise-1
- STATUS: RUNNING
- TYPE: Enterprise
- VERSION: 1.5.0
- URL: http://127.0.0.1:10000
- NAME: vcsserver-1
- STATUS: RUNNING
- TYPE: VCSServer
- VERSION: 3.5.0
- URL: http://127.0.0.1:10001
# Upgrade from version 1.5.0 to 3.5.0
$ rccontrol upgrade enterprise-1 --version 3.5.0
Checking for available update for enterprise-1 @ 1.5.0
Stopped enterprise-1
Initiating upgrade to version 3.5.0
...
****************************************
*** UPGRADE TO VERSION 45 SUCCESSFUL ***
****************************************
Note that RCE 3.x requires a new license please contact support@rhodecode.com
Upgrade of RhodeCode Enterprise successful.
Auto starting enterprise-1
Post Migration Tasks
--------------------
* From the |RCE| :menuselection:`Admin --> Settings --> VCS` page, check that
the :guilabel:`Repositories Location` is correctly pointing to your |repos|.
* Remap and rescan |repos| so that the new instance picks them up, see
:ref:`remap-rescan`.