Skip to content

Commit

Permalink
More updates to docker compose deployment
Browse files Browse the repository at this point in the history
  • Loading branch information
@garrettjstevens
garrettjstevens committed Dec 18, 2024
1 parent 9bc9848 commit f79de02
Show file tree
Hide file tree
Showing 5 changed files with 173 additions and 140 deletions.
90 changes: 3 additions & 87 deletions packages/apollo-collaboration-server/.development.env
View file
Original file line number Diff line number Diff line change
@@ -1,102 +1,18 @@
##############
## REQUIRED ##
##############

# URL
# Make sure to add new env variables to the docs page on the website
URL=http://localhost:3999

# Name of your server (shown during the login process)
NAME=Demo Server

# MongoDB connection
MONGODB_URI=mongodb://127.0.0.1:27017/apolloDb
# Alternatively, can be a path to a file with the URI
# MONGODB_URI_FILE=/run/secrets/mongodb-uri

# Output folder for uploaded files
FILE_UPLOAD_FOLDER=./test/uploaded

# Secret used to encode JWT tokens
JWT_SECRET=84b5edd3-6c4e-42f3-9711-2f294c07df19
# Alternatively, can be a path to a file with the client secret
# JWT_SECRET_FILE=/run/secrets/jwt-secret

# Secret used to encode express sessions
SESSION_SECRET=g9fGaRuw06T7hs960Tm7KYyfcFaYEIaG9jfFnVEQ4QyFXmq7
# Alternatively, can be a path to a file with the session secret
# SESSION_SECRET_FILE=/run/secrets/session-secret

##############################################################################
## To enable users to log in, you need either (or both) Google or Microsoft ##
## OAuth configured. Without them, only userless guest access is possible. ##
##############################################################################

# Google client id and secret.
GOOGLE_CLIENT_ID=1000521104117-bhd8r4v11cc053g0b80ui00ss9s5fitv.apps.googleusercontent.com
# Alternatively, can be a path to a file with the client ID
# GOOGLE_CLIENT_ID_FILE=/run/secrets/google-client-id
GOOGLE_CLIENT_SECRET=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
# Alternatively, can be a path to a file with the client secret
# GOOGLE_CLIENT_SECRET_FILE=/run/secrets/google-client-secret

# Microsoft client id and secret.
MICROSOFT_CLIENT_ID=fabdd045-163c-4712-9d40-dbbb043b3090
# Alternatively, can be a path to a file with the client ID
# MICROSOFT_CLIENT_ID_FILE=/run/secrets/microsoft-client-id
MICROSOFT_CLIENT_SECRET=~Gr8Q~h6RTU7SMC-fjNxXy_~nabTD-ME_rFyLa.M
# Alternatively, can be a path to a file with the client secret
# MICROSOFT_CLIENT_SECRET_FILE=/run/secrets/microsoft-client-secret

##############
## OPTIONAL ##
##############

# Description of what is hosted on your server
DESCRIPTION=A server for Apollo development purposes

# URL (relative or absolute) of the Apollo JBrowse plugin.
# Defaults to relative URL 'apollo.js'
PLUGIN_LOCATION=http://localhost:9000/dist/jbrowse-plugin-apollo.umd.development.js
FEATURE_TYPE_ONTOLOGY_LOCATION=http://localhost:9000/test_data/so-v3.1.json

# Application port, defaults to 3999
# PORT=3999

# Enable all CORS requests, defaults to true
# CORS=true

# Comma-separated list of log levels to output
# Possible values are: error, warn, log, debug, verbose.
# Defaults to error,warn,log
LOG_LEVELS=error,warn,log,debug

# Reference sequence chunk size, defaults to 262144 (256 KiB)
CHUNK_SIZE=500

# Default new user role, possible values are admin, user, readOnly, and none
# Defaults to none
# DEFAULT_NEW_USER_ROLE=none

# Whether to broadcast users locations, defaults to true
# BROADCAST_USER_LOCATION=true

# Whether to allow a root user that can log in with a name and password. All
# other users (besides guest) must sign in with an authentication provider.
# Defaults to false
# ALLOW_ROOT_USER=false
# The root user password, required if ALLOW_ROOT_USER is true
# ROOT_USER_PASSWORD=password
# Alternatively, can be a path to a file with the root user password
# ROOT_USER_PASSWORD_FILE=/run/secrets/root-user-password

# Whether to allow guest users who do not have to log in, defaults to false
ALLOW_ROOT_USER=ftrue
ROOT_USER_PASSWORD=password
ALLOW_GUEST_USER=true
# If guest users are allowed, what role will they have
# Possible values are admin, readOnly and user; defaults to readonly
# GUEST_USER_ROLE=readOnly

# Comma-separated list of Apollo plugins to use
# PLUGIN_URLS=https://example.com/apollo-plugin-example.umd.production.min.js
# Alternatively, can be a path to a file with a list of plugin URLs, one URL per
# line
# PLUGIN_URLS_FILE=/data/plugin-urls
14 changes: 7 additions & 7 deletions packages/website/docs/getting-started/deployment/01-background.md
View file
Original file line number Diff line number Diff line change
@@ -1,11 +1,11 @@
# Background

A full deployment of a collaborative Apollo instance is made up of several
different components. When setting up Apollo, you'll have to decide how you
want to handle each of these components. We provide some examples of how to
deploy Apollo, but the deployment can be customized to fit your needs. For
example, you may want to utilize an existing MongoDB installation (perhaps
managed by your institution) and deploy the rest of Apollo using Docker.
different components. When setting up Apollo, you'll have to decide how you want
to handle each of these components. We provide some examples of how to deploy
Apollo, but the deployment can be customized to fit your needs. For example, you
may want to utilize an existing MongoDB installation (perhaps managed by your
institution) and deploy the rest of Apollo using Docker.

Here we'll review the different parts of Apollo that each deployment strategy
will need to consider.
Expand Down Expand Up @@ -53,7 +53,7 @@ collaboration server, or it can be external.

## Deployment examples

- [Deploying with Docker](02-docker-compose.md)
- [Deploying with Docker](./02-deployment-examples/01-docker-compose.md)
- Other examples coming soon

## Customizing your deployment
Expand All @@ -63,4 +63,4 @@ settings and guest user access. You'll most likely want to then configure user
logins, which we cover in our [Login Management](03-login-management.md) guide.

We also cover more options for customizing Apollo in our
[Configuration options](04-configuration-options.md) guide.
[Configuration options](04-configuration-options.md) guide.
96 changes: 51 additions & 45 deletions ...g-started/deployment/02-docker-compose.md → ...-deployment-examples/01-docker-compose.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -74,7 +74,8 @@ services:
client:
build:
args:
JBROWSE_VERSION: 2.13.1
JBROWSE_VERSION: 2.18.0
JBROWSE_VERSION: 0.2.2
context: .
depends_on:
- apollo-collaboration-server
Expand Down Expand Up @@ -147,6 +148,8 @@ volumes:
```Dockerfile title="Dockerfile"
FROM httpd:alpine
ARG JBROWSE_VERSION
ARG APOLLO_VERSION
COPY <<EOF /usr/local/apache2/conf/httpd.conf.append
LogLevel debug
LoadModule proxy_module modules/mod_proxy.so
Expand All @@ -163,10 +166,10 @@ set -o errexit
set -o nounset
set -o pipefail
cat /usr/local/apache2/conf/httpd.conf.append >> /usr/local/apache2/conf/httpd.conf
wget https://github.com/GMOD/jbrowse-components/releases/download/v2.18.0/jbrowse-web-v2.18.0.zip
unzip -o jbrowse-web-v2.18.0.zip
rm jbrowse-web-v2.18.0.zip
wget --output-document=- --quiet https://registry.npmjs.org/@apollo-annotation/jbrowse-plugin-apollo/-/jbrowse-plugin-apollo-0.2.1.tgz | \
wget --output-document jbrowse-web.zip https://github.com/GMOD/jbrowse-components/releases/download/v$JBROWSE_VERSION/jbrowse-web-v$JBROWSE_VERSION.zip
unzip -o jbrowse-web.zip
rm jbrowse-web.zip
wget --output-document=- --quiet https://registry.npmjs.org/@apollo-annotation/jbrowse-plugin-apollo/-/jbrowse-plugin-apollo-$APOLLO_VERSION.tgz | \
tar --extract --gzip --file=- --strip=2 package/dist/jbrowse-plugin-apollo.umd.production.min.js
mv jbrowse-plugin-apollo.umd.production.min.js apollo.js
wget --quiet https://github.com/The-Sequence-Ontology/SO-Ontologies/raw/refs/heads/master/Ontology_Files/so.json
Expand Down Expand Up @@ -226,15 +229,17 @@ compose file:
client:
build:
args:
APOLLO_VERSION: 0.1.0
JBROWSE_VERSION: 2.10.3
FORWARD_HOSTNAME: apollo-collaboration-server
FORWARD_PORT: 3999
JBROWSE_VERSION: 2.18.0
JBROWSE_VERSION: 0.2.2
context: .
depends_on:
- apollo-collaboration-server
ports:
- '80:80'
volumes:
- /home/ec2-user/deployment/data/:/usr/local/apache2/htdocs/data/
- /home/ec2-user/deployment/demoData/:/usr/local/apache2/htdocs/demoData/
restart: unless-stopped
```
This service will be a static file server that serves the JBrowse and Apollo
Expand All @@ -251,13 +256,11 @@ specify when deploying your app.
Docker Compose will expect this Dockerfile to be named `Dockerfile` and be
located next to the `compose.yml` in the filesystem. The above Dockerfile
configures the file server, downloads the specified versions of Apollo and
JBrowse, and adds the JBrowse and Apollo configuration. The `FORWARD_HOSTNAME`
and `FORWARD_PORT` args should match the service name and port of the Apollo
Collaboration Server service (described in the next section).
JBrowse, and adds the JBrowse and Apollo configuration.

The configuration added to the `httpd.conf` file in that Dockerfile makes it so
that any request that comes to the server that doesn't match a file hosted on
the server is forwarded to the Apollo Collaboration Server.
that any request that starts with the path `/apollo/` gets sent to the
collaboration server, while any other requests are handled normally by Apache.

The `depends_on` section makes sure the collaboration server has started before
starting the client, and the `port` section makes the container's server
Expand All @@ -270,22 +273,16 @@ compose file:

```yml
apollo-collaboration-server:
image: ghcr.io/gmod/apollo-collaboration-server:development
image: ghcr.io/gmod/apollo-collaboration-server
depends_on:
mongo-node-1:
condition: service_healthy
env_file: .env
environment:
MONGODB_URI: mongodb://mongo-node-1:27017,mongo-node-2:27018/apolloDb?replicaSet=rs0
FILE_UPLOAD_FOLDER: /data/uploads
ALLOW_GUEST_USER: true
URL: http://my-apollo-site.org
JWT_SECRET: change_this_value
SESSION_SECRET: change_this_value
env_file: apollo.env
ports:
- 3999:3999
volumes:
- uploaded-files-volume:/data/uploads
restart: unless-stopped
```

This service uses a published Docker image for its container. It also uses
Expand All @@ -294,31 +291,39 @@ before starting the collaboration server, and defines which port the app is
exposed on.

The collaboration server is configured with environment variables, often in a
`.env` file. However, we use the `environment` option to set a couple variables
whose value depends on other places in the compose file, to try to keep the
related options all in one place. These two variables are `MONGODB_URI` and
`FILE_UPLOAD_FOLDER`. The example URI is
`.env` file. Here we use `apollo.env` as the name of our environment variable
file. You could also specify the environment variables inline under an
`environment` section in the service.

Let's talk about a few of the options for the collaboration server specified in
the `.env` file:

##### `NAME`

A name for your Apollo instance. It is shown in the UI during the login process.

##### `MONGODB_URI`

In this example, it is
`mongodb://mongo-node-1:27017,mongo-node-2:27018/apolloDb?replicaSet=rs0`. If
you change the names of either of the MongoDB services, their ports, or add or
remove a MongoDB service, be sure to update this value. The value of
`FILE_UPLOAD_FOLDER` should match what's on the right side of the colon in the
`volumes` section (e.g. `/data/uploads`).

There are a few other variables that need to be configured for the Apollo
Collaboration Server to work. They are `URL`, `JWT_SECRET`, and `SESSION_SECRET`
variables. `URL` is the URL of the server that's hosting Apollo. We'll discuss
this more in a later section when talking about authentication. You can think of
`JWT_SECRET` and `SESSION_SECRET` as kind of like passwords. They need to be a
random string, but should be the same each time you run the server so that user
sessions are not invalidated (unless you want to intentionally invalidate user
sessions). You can use a password generator to create them.
remove a MongoDB service, be sure to update this value.

You can put these variables in the `environment` section, or you can put them in
a `.env` file, which has a format that looks like this
##### `FILE_UPLOAD_FOLDER`

```env
URL=https://my-apollo-site.org
```
This should match what's on the right side of the colon in the `volumes` section
(e.g. `/data/uploads`).

##### `URL`

The URL of the server that's hosting Apollo.

##### `JWT_SECRET` and `SESSION_SECRET`

You can think of these as kind of like passwords. They need to be a random
string, but should be the same each time you run the server so that user
sessions are not invalidated (unless you want to intentionally invalidate user
sessions). You can use a password generator to create them.

#### MongoDB

Expand Down Expand Up @@ -417,4 +422,5 @@ docker compose down
We are now ready to access Apollo. Open a web browser and got the URL you
entered in the `apollo.env` file above. You should see a JBrowse instance with a
prompt to log in as a guest. You should see a view with an assembly selector,
but there aren't any assemblies yet, so there's not much we can do for now.
but there aren't any assemblies yet. You're now ready to head over to our
[Admin guide](../../../category/admin) to learn how to load data into Apollo.
4 changes: 4 additions & 0 deletions packages/website/docs/getting-started/deployment/02-deployment-examples/_category_.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
{
"label": "Examples",
"position": 2
}
Loading

0 comments on commit f79de02

Please sign in to comment.