Migrating from Oracle OpenGrok to Sourcegraph for code search
- Migration guide
Sourcegraph is a self-hosted code search and intelligence tool that helps developers find, review, understand, and debug code. Organizations that switch from OpenGrok to Sourcegraph typically cite the following reasons:
- Sourcegraph supports searching any revision (not just specific branches) and does not require waiting for periodic reindexing.
- Sourcegraph’s query syntax, user interface, and integrations are superior and easier to use.
- Sourcegraph’s code intelligence, has better language support (hover tooltips, definitions, references, implementations, etc.) and is based on the Language Server Protocol standard.
- The Sourcegraph API is more powerful, better documented, and easier to use than OpenGrok’s API.
- Sourcegraph scales to more repositories/users and supports Kubernetes-based clustered/high-availability deployments better (with the cluster deployment option).
Both Sourcegraph and OpenGrok are self-hosted, and your code never touches Sourcegraph’s (or Oracle’s) servers.
One key feature of OpenGrok that Sourcegraph lacks is support for Subversion, Mercurial, CVS, and Perforce repositories. Sourcegraph only supports Git repositories.
Oracle releases OpenGrok under the open-source CDDL license and does not (currently) have any monetization plans for it. Sourcegraph is a commercial product, with a free tier and paid premium features available.
Every organization’s needs are different. Install and use Sourcegraph for free to see if it’s right for your organization.
For more information about Sourcegraph, see:
Migrating from Oracle OpenGrok to Sourcegraph consists of 4 steps:
- Deploying Sourcegraph
- Configuring repositories
- Configuring user authentication
- Rolling out Sourcegraph organization-wide
The following sections guide you through the migration process.
You can deploy Sourcegraph in 2 ways:
- Single Docker container: single-server deployment from the
- Kubernetes cluster: cluster deployment using Kubernetes for 1,000s of repositories/users
The fastest way to try it is to run Sourcegraph Server locally with the quickstart instructions.
Choose a deployment option and follow the instructions. When you’ve signed into your Sourcegraph instance as a site admin, continue to the next section.
Sourcegraph and Oracle OpenGrok differ in how they access repositories:
- “Passive”: OpenGrok reads all repositories underneath the
SRC_ROOTpath on disk. You place repositories there and configure the sync.py tool to fetch updates.
- “Active”: Sourcegraph automatically handles cloning and updating repositories from code hosts (GitHub, GitLab, Bitbucket Server, AWS CodeCommit, etc..
Sourcegraph’s “active” model lets it:
- serve fresher repository data (to search and browse just-
git pushed data);
- synchronize the list of repositories on the code host (so that newly added repositories are searchable/browseable)
- offer code host integrations and “View file on code host” links
Sourcegraph also partially supports the “passive” model like OpenGrok, but it’s not recommended because you lose these benefits. To use it anyway, see “Add repositories already cloned to disk”.
To configure which repositories Sourcegraph will make available for searching and browsing:
- For repositories on popular code hosts, use the Quick configure actions on your Sourcegraph instance’s site admin “Site configuration” page.
- For other repositories and for more information, see “Add repositories” in the Sourcegraph documentation.
When you’ve added repositories and confirmed that you can search and browse them, continue to the next section.
Configuring user authentication
Like Oracle OpenGrok, Sourcegraph is self-hosted. You control who can access it. Sourcegraph supports many user authentication and security options:
- OpenID Connect user authentication and SAML user authentication (for Google/G Suite accounts, Okta, OneLogin, etc.)
- HTTP user authentication proxies
- Builtin username-password authentication
- TLS/SSL and other HTTP/HTTPS configuration
Rolling out Sourcegraph organization-wide
After you’ve set Sourcegraph up, it’s time to share it with your organization. Successful roll-outs of Sourcegraph typically involve the following steps.
- Send a message (in team chat or email) announcing Sourcegraph:
I set up Sourcegraph as a possible alternative to OpenGrok for code search. [Describe the perceived benefits vs. OpenGrok that are most relevant to your organization.]
- Search: [URL to an example search results page on your Sourcegraph instance]
- Code browsing: [URL to a code file page on your Sourcegraph instance]
[Include screenshots of your Sourcegraph instance here]
Post feedback at https://github.com/sourcegraph/sourcegraph [change if needed]
- Create an internal document based on the Sourcegraph tour, substituting links to and names of your organization’s code. This explains how Sourcegraph helps developers perform common tasks better.
- Encourage installation of the browser extension to get Sourcegraph code intelligence and search in your organization’s existing code host.
- Roll out the Chrome extension using G Suite automatic installation to everyone in your organization.
- Check the access logs for OpenGrok to see what users search for. Try searching for the same things on Sourcegraph, and ensure that you get the expected results. (Note: Sourcegraph’s search query syntax differs from OpenGrok’s.)
- Monitor your Sourcegraph instance’s site admin “Analytics” page to see who’s using it. Ask them for specific feedback. Also seek feedback from the most frequent users of OpenGrok.
If there are any blockers preventing your organization from switching to Sourcegraph, we’d love to hear from you so we can address them.