Skip to content

Commit

Permalink
Merge pull request #2221 from dolthub/gitbook-dev
Browse files Browse the repository at this point in the history 
update doltlab doc headings
  • Loading branch information
@coffeegoddd
coffeegoddd authored May 20, 2024
2 parents 50374f9 + 3985687 commit 213a7d8
Show file tree
Hide file tree
Showing 12 changed files with 1,818 additions and 1,807 deletions.
2 changes: 2 additions & 0 deletions packages/doltlab/content/SUMMARY.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,8 @@
## Reference

- [Installer](reference/installer.md)
- [Configuration file reference](reference/installer/configuration-file.md)
- [Command line reference](reference/installer/cli.md)

## Release Notes

Expand Down
76 changes: 38 additions & 38 deletions packages/doltlab/content/guides/administrator.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,35 +4,35 @@ title: "Administrator Guide"

This guide will cover how to perform common DoltLab administrator configuration and tasks for the latest versions of DoltLab, >= `v2.1.0`. These versions use the [installer](../reference/installer.md) binary included in DoltLab's `.zip` file. For instructions on running DoltLab in Enterprise mode and configuring exclusive Enterprise features, see the [Enterprise Guide](./enterprise.md). If you're using an older version of DoltLab that does not include the [installer](../reference/installer.md), please see the [pre-installer Admin guide](./pre-installer-administrator-guide.md).

1. [File issues and view release notes](#issues-release-notes)
2. [Backup DoltLab data](#backup-restore-volumes)
3. [Connect with the DoltLab team](#connect-with-doltlab-team)
1. [File issues and view release notes](#file-issues-and-view-release-notes)
2. [Backup DoltLab data](#backup-and-restore-volumes)
3. [Connect with the DoltLab team](#connect-with-the-doltlab-team)
4. [Send service logs to the DoltLab team](#send-service-logs)
5. [Authenticate a Dolt client to use a DoltLab account](#auth-dolt-client)
6. [Monitor DoltLab with cAdvisor and Prometheus](#prometheus)
7. [Connect DoltLab to an SMTP server](#connect-smtp-server)
8. [Connect DoltLab to an SMTP server with implicit TLS](#smtp-implicit-tls)
9. [Troubleshoot SMTP server connection problems](#troubleshoot-smtp-connection)
5. [Authenticate a Dolt client to use a DoltLab account](#authenticate-a-dolt-client-to-use-a-doltlab-account)
6. [Monitor DoltLab with cAdvisor and Prometheus](#monitor-doltlab-with-cadvisor-and-prometheus)
7. [Connect DoltLab to an SMTP server](#connect-doltlab-to-an-smtp-server)
8. [Connect DoltLab to an SMTP server with implicit TLS](#connect-doltlab-to-an-smtp-server-with-implicit-tls)
9. [Troubleshoot SMTP server connection problems](#troubleshoot-smtp-server-connection-problems)
10. [Set up a SMTP server using any Gmail address](#set-up-a-smtp-server-using-any-gmail-address)
11. [Prevent unauthorized user account creation](#prevent-unauthorized-users)
12. [Use an external database server with DoltLab](#use-external-database)
11. [Prevent unauthorized user account creation](#prevent-unauthorized-user-account-creation)
12. [Use an external database server with DoltLab](#use-an-external-database-server-with-doltlab)
13. [DoltLab Jobs](#doltlab-jobs)
14. [Disable usage metrics](#disable-metrics)
15. [Use a domain name with DoltLab](#use-domain)
16. [Run DoltLab on Hosted Dolt](#doltlab-hosted-dolt)
17. [Serve DoltLab over HTTPS natively](#doltlab-https-natively)
18. [Improve DoltLab performance](#doltlab-performance)
19. [Serve DoltLab behind an AWS Network Load Balancer](#doltlab-aws-nlb)
14. [Disable usage metrics](#disable-usage-metrics)
15. [Use a domain name with DoltLab](#use-a-domain-name-with-doltlab)
16. [Run DoltLab on Hosted Dolt](#run-doltlab-on-hosted-dolt)
17. [Serve DoltLab over HTTPS natively](#serve-doltlab-over-https-natively)
18. [Improve DoltLab performance](#improve-doltlab-performance)
19. [Serve DoltLab behind an AWS Network Load Balancer](#serve-doltlab-behind-an-aws-network-load-balancer)

<h1 id="issues-release-notes">File issues and view release notes</h1>
# File issues and view release notes

DoltLab's source code is currently closed, but you can file DoltLab issues the [issues repository](https://github.com/dolthub/doltlab-issues). Release notes are available [here](../../release-notes.md).

<h1 id="backup-restore-volumes">Backup and restore volumes</h1>
# Backup and restore volumes

DoltLab currently persists all data to local disk using Docker volumes. To backup or restore DoltLab's data, we recommend the following steps which follow Docker's official [volume backup and restore documentation](https://docs.docker.com/storage/volumes/#back-up-restore-or-migrate-data-volumes).

<h2 id="backup-restore-remote-data-user-data-dolt-server-data"><ins>Backing up and restoring remote data, user uploaded data, and Dolt server data with Docker</ins></h2>
## Backing up and restoring remote data, user uploaded data, and Dolt server data with Docker

To backup DoltLab's remote data, the database data for all database on a given DoltLab instance, leave DoltLab's services up and run:

Expand Down Expand Up @@ -144,7 +144,7 @@ docker run --rm --volumes-from doltlab_doltlabdb_1 -v $(pwd):/backup ubuntu bash

You can now restart DoltLab, and should see all data restored from the `tar` files.

<h2 id="backup-restore-dolt-server-backup"><ins>Backing up and restoring the Dolt Server using the `dolt backup` command</ins></h2>
## Backing up and restoring the Dolt Server using the `dolt backup` command

The quickest way to do this is with the `./doltlabdb/shell-db.sh` script generated by the [installer](../reference/installer.md):

Expand Down Expand Up @@ -206,11 +206,11 @@ dolthubapi

The database has now been successfully restored, and you can now restart DoltLab.

<h1 id="connect-with-doltlab-team">Connect with the DoltLab Team</h1>
# Connect with the DoltLab Team

If you need to connect to a DoltLab team member, the best way to do so is on [Discord](https://discord.gg/s8uVgc3), in the `#doltlab` server.

<h1 id="send-service-logs">Send Service Logs to DoltLab Team</h1>
# Send Service Logs to DoltLab Team

DoltLab is composed of [multiple services](https://www.dolthub.com/blog/2022-02-25-doltlab-101-services-and-roadmap/) running in a single Docker network via Docker compose. Logs for a particular service can be viewed using the `docker logs <container name>` command. For example, to view to logs of `doltlabapi` service, run:

Expand All @@ -233,7 +233,7 @@ chmod 0644 ./doltlab-api-logs.json

Finally, download the copied log file from your DoltLab host using `scp`. You can then send this and any other log files to the DoltLab team member you're working with via email.

<h1 id="auth-dolt-client">Authenticate a Dolt Client to use a DoltLab account</h1>
# Authenticate a Dolt Client to use a DoltLab account

To authenticate a Dolt client against a DoltLab remote, use the `--auth-endpoint`, `--login-url`, and `--insecure` arguments with the [dolt login](https://docs.dolthub.com/cli-reference/cli#dolt-login) command.

Expand Down Expand Up @@ -283,7 +283,7 @@ Paste the public key into the "Public Key" field, write a description in the "De

Your Dolt client is now authenticated for this DoltLab account.

<h1 id="prometheus">Monitor DoltLab with cAdvisor and Prometheus</h1>
# Monitor DoltLab with cAdvisor and Prometheus

[Prometheus](https://prometheus.io/) [gRPC](https://grpc.io/) service metrics for [DoltLab's Remote API Server](https://www.dolthub.com/blog/2022-02-25-doltlab-101-services-and-roadmap/#doltlab-remoteapi-server), `doltlabremoteapi`, and [DoltLab's Main API server](https://www.dolthub.com/blog/2022-02-25-doltlab-101-services-and-roadmap/#doltlab-api-server), `doltlabapi`, are published on port `7770`.

Expand Down Expand Up @@ -332,7 +332,7 @@ docker run -d --add-host host.docker.internal:host-gateway --name=prometheus -p

`--add-host host.docker.internal:host-gateway` is only required if you are running the Prometheus server _on_ your DoltLab host. If its running elsewhere, this argument may be omitted, and the `host.docker.internal` hostname in `prometheus.yml` can be changed to the hostname of your DoltLab host.

<h1 id="connect-smtp-server">Connect DoltLab to an SMTP server</h1>
# Connect DoltLab to an SMTP server

DoltLab's most basic configuration does not require connection to an SMTP server. In this configuration, only the default user can use the DoltLab instance, as new account creation on DoltLab _requires_ an SMTP server to be connected to the instance. To enable account creation on DoltLab and enable its full suite of features, connect DoltLab to an SMTP server by editing `./installer_config.yaml` [to configure the SMTP server connection](#installer-config-reference-smtp).

Expand Down Expand Up @@ -363,7 +363,7 @@ Alternatively, instead of using `./installer_config.yaml`, the [installer](../re
`--smtp-password`, _required_ for authentication methods `plain` and `login`, the password for authenticating against the SMTP server.
`--smtp-oauth-token`, _required_ for authentication method `oauthbearer`,the oauth token used for authentication against the SMTP server.

<h1 id="smtp-implicit-tls">Connect DoltLab to an SMTP server with implicit TLS</h1>
# Connect DoltLab to an SMTP server with implicit TLS

Edit `./installer_config.yaml` [to configure the SMTP server connection](#installer-config-reference-smtp) set `smtp.implicit_tls` as `true`.

Expand All @@ -390,7 +390,7 @@ Save these changes, then re-run the [installer](../reference/installer.md).

Alternatively, use `--smtp-implicit-tls=true` with the [installer](../reference/installer.md) to use implicit TLS. Use `--smtp-insecure-tls=true` to skip TLS verification.

<h1 id="troubleshoot-smtp-connection">Troubleshoot SMTP server connection problems</h1>
# Troubleshoot SMTP server connection problems

DoltLab requires a connection to an existing SMTP server in order for users to create accounts, verify email addresses, reset forgotten passwords, and collaborate on databases.

Expand Down Expand Up @@ -561,7 +561,7 @@ ubuntu@ip-10-2-0-24:~/doltlab$

Running the newly generated `./start.sh` will start DoltLab connected to Gmail.

<h1 id="prevent-unauthorized-users">Prevent unauthorized user account creation</h1>
# Prevent unauthorized user account creation

DoltLab supports explicit email whitelisting to prevent account creation by unauthorized users.

Expand Down Expand Up @@ -598,7 +598,7 @@ Execute the following `INSERT` to allow the user with `[email protected]` to c
INSERT INTO email_whitelist_elements (email_address, updated_at, created_at) VALUES ('[email protected]', CURRENT_TIMESTAMP, CURRENT_TIMESTAMP);
```

<h1 id="use-external-database">Use an external database server with DoltLab</h1>
# Use an external database server with DoltLab

In the external Dolt database, prior to connecting your DoltLab instance, run the following SQL statements:

Expand All @@ -613,13 +613,13 @@ Next, stop your DoltLab instance if it is running. Then, supply the `--doltlabdb

When you restart your instance it should now be connected to your external Dolt database.

<h1 id="doltlab-jobs">DoltLab Jobs</h1>
# DoltLab Jobs

DoltLab Jobs are stand-alone, long-running Docker containers that perform specific tasks for DoltLab users behind the scenes.

As a result, DoltLab may consume additional memory and disk, depending on the number of running Jobs and their workload.

<h1 id="disable-metrics">Disable usage metrics</h1>
# Disable usage metrics

By default, DoltLab collects first-party metrics for deployed instances. We use DoltLab's metrics to determine how many resources to allocate toward its development and improvement.

Expand All @@ -638,7 +638,7 @@ Save these changes, then rerun the [installer](../reference/installer.md) to reg

Alternatively, to disable first-party metrics using command line arguments, run the [installer](../reference/installer.md) with `--disable-usage-metrics=true`.

<h1 id="use-domain">Use a domain name with DoltLab</h1>
# Use a domain name with DoltLab

It's common practice to provision a domain name to use for a DoltLab instance. To do so, secure a domain name and map it to the _stable_, public IP address of the DoltLab host. Then, supply the domain name as the value to the `--host` argument used with the [installer](../reference/installer.md).

Expand Down Expand Up @@ -669,13 +669,13 @@ Restart your DoltLab instance with `./start.sh`.

In the event you are configuring your domain name with an Elastic Load Balancer, ensure that it specifies Target Groups for each of the ports required to operate DoltLab, `80`, `100`, `4321`, and `50051`.

<h1 id="doltlab-hosted-dolt">Run DoltLab on Hosted Dolt</h1>
# Run DoltLab on Hosted Dolt

DoltLab can be configured to use a [Hosted Dolt](https://hosted.doltdb.com) instance as its application database. This allows DoltLab administrators to use the feature-rich SQL workbench Hosted Dolt provides to interact with their DoltLab database.

To configure a DoltLab to use a Hosted Dolt, follow the steps below as we create a sample DoltLab Hosted Dolt instance called `my-doltlab-db-1`.

<h2 id="doltlab-hosted-dolt-create-deployment">Create a Hosted Dolt deployment</h2>
## Create a Hosted Dolt deployment

To begin, you'll need to create a Hosted Dolt deployment that your DoltLab instance will connect to. We've created a [video tutorial](https://www.dolthub.com/blog/2022-05-20-hosted-dolt-howto/) for how to create your first Hosted Dolt deployment, but briefly, you'll need to create an account on [hosted.doltdb.com](https://hosted.doltdb.com) and then click the "Create Deployment" button.

Expand Down Expand Up @@ -722,7 +722,7 @@ You can do this by running these statements from the Hosted workbench SQL consol

This instance is now ready for a DoltLab connection.

<h2>Rerun DoltLab's Installer</h2>
## Rerun DoltLab's Installer

To connect DoltLab to `my-doltlab-db-1`, ensure that your DoltLab instance is stopped.

Expand Down Expand Up @@ -757,7 +757,7 @@ Start DoltLab using the `./start.sh` script generated by the [installer](../refe

![Hosted Dolt Workbench](../.gitbook/assets/hosted_dolt_workbench.png)

<h1 id="doltlab-https-natively">Serve DoltLab over HTTPS natively</h1>
# Serve DoltLab over HTTPS natively

First, make sure that port `443` is open on the host running DoltLab (as well as the other required ports `100`, `4321`, and `50051`) and that you have a valid TLS certificate configured for your DoltLab host. We recommend creating a TLS certificate using [certbot](https://certbot.eff.org/).

Expand Down Expand Up @@ -789,7 +789,7 @@ Alternatively, if you prefer to use command line flags, run the [installer](../r

You can now restart DoltLab with the `./start.sh` script, and it will be served over HTTPS.

<h1 id="doltlab-performance">Improve DoltLab performance</h1>
# Improve DoltLab performance

It is possible to limit the number of concurrent Jobs running on a DoltLab host, which might be starving the host for resources and affecting DoltLab's performance.

Expand Down Expand Up @@ -823,7 +823,7 @@ Alternatively, you can use the following command line arguments with the [instal
--job-max-retries="5
```

<h1 id="doltlab-aws-nlb">Serve DoltLab behind an AWS Network Load Balancer</h1>
# Serve DoltLab behind an AWS Network Load Balancer

The following section describes how to setup an [AWS Network Load Balancer (NLB)](https://aws.amazon.com/elasticloadbalancing/network-load-balancer/) for a DoltLab instance.

Expand Down
Loading

0 comments on commit 213a7d8

Please sign in to comment.