diff --git a/docs/source/GettingStarted.rst b/docs/source/GettingStarted.rst index f0c1758..995b737 100644 --- a/docs/source/GettingStarted.rst +++ b/docs/source/GettingStarted.rst @@ -1,5 +1,5 @@ ###################################################################################### -Getting started +Tutorial: Getting started ###################################################################################### This guide will help you get set up to use Galv. diff --git a/docs/source/HowToAWS.rst b/docs/source/HowToAWS.rst new file mode 100644 index 0000000..3532901 --- /dev/null +++ b/docs/source/HowToAWS.rst @@ -0,0 +1,146 @@ +###################################################################################### +How-to: Set up AWS S3 for Galv +###################################################################################### + +Galv servers usually provide a limited amount of storage to each Lab. +To store files exceeding this quota, you can set up an AWS S3 bucket for your Lab, +and any Teams and Harvesters in your Lab will be able to store data there. + +The basic steps are: + +#. Create an AWS account +#. Create an S3 bucket +#. Configure the bucket CORS settings to allow Galv to access it +#. Create an IAM user with access to the bucket +#. Set up the AWS credentials in Galv + +Create an AWS account +================================================================================== + +If you don't already have an AWS account, you can create one at https://aws.amazon.com/ + +Create an S3 bucket +================================================================================== + +Once you've logged in to AWS, go to the S3 service and create a new bucket. +You can find the S3 service in the "Storage" section of the AWS Management Console, +or you can search for it in the search bar. + +.. thumbnail:: img/aws-create_bucket.png + :alt: Creating a bucket + :align: center + :title: Creating a bucket + +We won't go into the details of creating a bucket here, but you can find more information +in the AWS documentation: https://docs.aws.amazon.com/AmazonS3/latest/userguide/creating-bucket.html + +Configure the bucket CORS settings +================================================================================== + +Once you've created the bucket, you'll need to configure the CORS settings to allow Galv to access it. +You can do this by clicking on the bucket name in the S3 console, then going to the "Permissions" tab, +then going to the "Cross-origin resource sharing (CORS)" section. + +.. code-block:: json + + [ + { + "AllowedHeaders": [ + "*" + ], + "AllowedMethods": [ + "HEAD", + "GET" + ], + "AllowedOrigins": [ + "https://galv-backend-dev.fly.dev", + "https://galv-frontend.dev.fly.dev" + ], + "ExposeHeaders": [], + "MaxAgeSeconds": 3600 + } + ] + +Set the "AllowedOrigins" to the URLs of your Galv frontend and backend servers. +If you're setting things up in the frontend, the frontend URL is the URL of the site you're on, +and the backend URL can be found by going to the 'Harvesters' tab and reading the text at the top. + +Once you've created the bucket, copy its ARN because you'll need it later. +On the main Buckets screen, select the bucket radio button and click 'Copy ARN'. + +Create an IAM user with access to the bucket +================================================================================== + +Next, you'll need to create an IAM user with access to the S3 bucket. +You'll want this user to have the minimum permissions necessary to access the bucket, +because the credentials will be stored in Galv and could be exposed if the server is compromised. + +Galv will need to read and write files to the bucket, but it doesn't need to be able to change bucket settings. + +First, go to the IAM service in the AWS Management Console. +Then go to the Policies section under 'Access management' and create a new policy. + +.. thumbnail:: img/aws-create_policy.png + :alt: Creating a policy + :align: center + :title: Creating a policy + +You can use the JSON editor to create a policy like this: + +.. code-block:: json + + { + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "VisualEditor0", + "Effect": "Allow", + "Action": [ + "s3:ListBucketMultipartUploads", + "s3:ListBucket", + "s3:PutBucketCORS", + "s3:GetBucketAcl", + "s3:ListMultipartUploadParts", + "s3:PutObject", + "s3:GetObjectAcl", + "s3:GetObject", + "s3:GetObjectTorrent", + "s3:GetBucketCORS", + "s3:GetObjectVersionAcl", + "s3:DeleteObject", + "s3:GetObjectVersion" + ], + "Resource": [ + "arn:aws:s3:::my-galv-bucket/*", + "arn:aws:s3:::my-galv-bucket" + ] + } + ] + } + +Make sure to replace the entries in "Resource" with the ARN of your bucket, which you can find in the bucket properties. + +Next, create a new user in the IAM service and attach the policy you just created to the user. +If you prefer to use Groups, you can create a Group and attach the policy to the Group instead, +then add the user to the Group. + +Finally, create an access key for the user and save the Access Key ID and Secret Access Key. +Do that by selecting your user from the Users section and going to the 'Security credentials' tab. +Create an 'Access key' for a 'Third-party service' or 'Application running outside AWS'. +Copy the Access Key ID and Secret Access Key because you'll need to enter them in Galv. + +Set up the AWS credentials in Galv +================================================================================== + +Finally, you'll need to enter the AWS credentials in Galv so that it can access the S3 bucket. +Click on the 'Additional storage' icon in the navigation bar, then click 'Create new additional storage'. + +You can fill out the form using the Access Key ID and Secret Access Key you created in the previous step, +and you'll also need the bucket name and the AWS region the bucket is in. +The 'location' field allows you to specify a path within your bucket where files will be stored. + +Fill out the information, make sure the storage is set to 'enabled', +and click the green floppy disc icon to create your storage. + +You should now be able to upload files to your S3 bucket from Galv, +and Galv will take care of making sure that the appropriate people can access them. diff --git a/docs/source/conf.py b/docs/source/conf.py index ae06545..8118c28 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -11,7 +11,7 @@ project = 'Galv Frontend' copyright = '2023, Oxford RSE' author = 'Oxford RSE' -release = '2.0.0' +release = '2.1.0' # -- General configuration --------------------------------------------------- # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration diff --git a/docs/source/img/aws-create_bucket.png b/docs/source/img/aws-create_bucket.png new file mode 100644 index 0000000..747b413 Binary files /dev/null and b/docs/source/img/aws-create_bucket.png differ diff --git a/docs/source/img/aws-create_policy.png b/docs/source/img/aws-create_policy.png new file mode 100644 index 0000000..3b4bcdf Binary files /dev/null and b/docs/source/img/aws-create_policy.png differ diff --git a/docs/source/index.rst b/docs/source/index.rst index 5a113b7..5c5a1bd 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -22,9 +22,19 @@ to provide a modern, responsive, and intuitive user interface to the backend `RE GettingStarted UserGuide + HowToAWS + DeploymentGuide DevelopmentGuide +Backend and Harvester documentation +-------------------------------------------------------------------------------------- + +The backend and harvester documentation can be found at the following links: + +* `Galv Backend `_ +* `Galv Harvester `_ + Indices and tables ====================================================================================== diff --git a/docs/tags.json b/docs/tags.json index 2ede89d..0e94d43 100644 --- a/docs/tags.json +++ b/docs/tags.json @@ -1 +1 @@ -["v2.0.0","main"] \ No newline at end of file +["v2.1.0","main"] \ No newline at end of file diff --git a/package.json b/package.json index fe71069..23725f5 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "galv-client", - "version": "2.0.0", + "version": "2.1.0", "private": true, "proxy": "http://app/", "dependencies": { @@ -8,7 +8,7 @@ "@canvasjs/react-charts": "^1.0.0", "@emotion/react": "^11.10.5", "@emotion/styled": "^11.10.5", - "@galv/galv": "2.1.45", + "@galv/galv": "2.2.0", "@mui/base": "5.0.0-beta.33", "@mui/icons-material": "^5.10.15", "@mui/lab": "^5.0.0-alpha.109", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 663bec0..a6c4d3f 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -18,8 +18,8 @@ dependencies: specifier: ^11.10.5 version: 11.11.0(@emotion/react@11.11.1)(@types/react@18.2.42)(react@18.2.0) '@galv/galv': - specifier: 2.1.45 - version: 2.1.45 + specifier: 2.2.0 + version: 2.2.0 '@mui/base': specifier: 5.0.0-beta.33 version: 5.0.0-beta.33(@types/react@18.2.42)(react-dom@18.2.0)(react@18.2.0) @@ -1013,8 +1013,8 @@ packages: resolution: {integrity: sha512-9TANp6GPoMtYzQdt54kfAyMmz1+osLlXdg2ENroU7zzrtflTLrrC/lgrIfaSe+Wu0b89GKccT7vxXA0MoAIO+Q==} dev: false - /@galv/galv@2.1.45: - resolution: {integrity: sha512-PQgkVTd7pBQBIBWcv6kkglRvNXXT0pghgst65kVnYvUCJ/4LWjZJpn68b2g5hRnMsSved//gbJ3vgcTy57UazQ==} + /@galv/galv@2.2.0: + resolution: {integrity: sha512-teY6P+ur0AkT48LMhbmqgZdQz60at9mHzdH7LhA/x8nfK1ndFiTTE6rjpIxmFIl592yM0+y7H1JJZOa+o4vBTw==} dependencies: axios: 0.21.4 transitivePeerDependencies: diff --git a/src/constants.ts b/src/constants.ts index e3e21ed..fd4e039 100644 --- a/src/constants.ts +++ b/src/constants.ts @@ -793,7 +793,7 @@ export const FIELDS = { ...generic_fields, name: {read_only: false, type: "string", priority: PRIORITY_LEVELS.IDENTITY}, lab: {read_only: true, type: key_to_type(LOOKUP_KEYS.LAB), priority: PRIORITY_LEVELS.CONTEXT}, - quota: {read_only: true, type: "number", priority: PRIORITY_LEVELS.SUMMARY}, + quota_bytes: {read_only: true, type: "number", priority: PRIORITY_LEVELS.SUMMARY}, bytes_used: {read_only: true, type: "number", priority: PRIORITY_LEVELS.SUMMARY}, priority: {read_only: false, type: "number", priority: PRIORITY_LEVELS.SUMMARY}, enabled: {read_only: false, type: "boolean", priority: PRIORITY_LEVELS.SUMMARY},