Skip to content

Commit

Permalink
Updates instructions for installing or upgrading
Browse files Browse the repository at this point in the history
  • Loading branch information
@chiatt
chiatt committed Dec 2, 2024
1 parent 49b0917 commit 912ee73
Show file tree
Hide file tree
Showing 2 changed files with 124 additions and 112 deletions.
111 changes: 111 additions & 0 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,3 +5,114 @@ Arches for Science an Arches Application designed to help conservation scientist

Please see the [project page](http://archesproject.org/) for more information on the Arches project.


## Installation

If you are installing Arches for Science for the first time, you can install it as an Arches application into a project or run it directly as an Arches project. Running Arches for Science as a project can provide some convienience if you are a developer contributing to the Arches for Science project. Otherwise, **we strongly recommend running Arches for Science as an Arches Application** within a project because that will allow greater flexibility in customizing your project without the risk of conflicts when upgrading to the next version of Arches for Science.


### If installing for development
Clone the arches-for-science repo and checkout the latest `dev/x.x.x` branch.
Navigate to the `arches-for-science` directory from your terminal and run:
```
pip install -e .
```

### If installing for deployment, run:
```
pip install arches-for-science
```

`Important`: Installing the arches-for-science app will install Arches as a dependency. This may replace your current install of Arches with a version from PyPi. If you've installed Arches for development using the `--editable` flag, you'll need to re pip install arches after installing arches-for-science

## Project Configuration

1. If you don't already have an Arches project, you'll need to create one by following the instructions in the Arches [documentation](http://archesproject.org/documentation/).
Since Arches for Science uses `Cantaloupe` as its IIIF server, take notice of the
Cantaloupe [installation instructions](https://arches.readthedocs.io/en/stable/developing/advanced/managing-and-hosting-iiif/), too.

2. When your project is ready, add "arches_templating", "arches_for_science", and "pgtrigger" to INSTALLED_APPS **below** the name of your project:
```
INSTALLED_APPS = (
...
"my_project_name",
"arches_templating",
"arches_for_science",
"pgtrigger",
)
```
3. Make sure the following settings are added to your project
```
FUNCTION_LOCATIONS.append("arches_for_science.functions")
TEMPLATES = build_templates_config(
debug=DEBUG,
app_root=APP_ROOT,
context_processors=[
"django.contrib.auth.context_processors.auth",
"django.template.context_processors.debug",
"django.template.context_processors.i18n",
"django.template.context_processors.media",
"django.template.context_processors.static",
"django.template.context_processors.tz",
"django.template.context_processors.request",
"django.contrib.messages.context_processors.messages",
"arches.app.utils.context_processors.livereload",
"arches.app.utils.context_processors.map_info",
"arches.app.utils.context_processors.app_settings",
"arches_for_science.utils.context_processors.project_settings",
],
)
RENDERERS += [
{
"name": "xy-reader",
"title": "XY Data File Reader",
"description": "Use for all instrument outputs with x-y data",
"id": "e93b7b27-40d8-4141-996e-e59ff08742f3",
"iconclass": "fa fa-bolt",
"component": "views/components/cards/file-renderers/xy-reader",
"ext": "txt",
"type": "text/plain",
"exclude": "",
},
]
XY_TEXT_FILE_FORMATS = ["txt"]
X_FRAME_OPTIONS = "SAMEORIGIN"
```
4. Next ensure arches and arches_for_science are included as dependencies in package.json
```
"dependencies": {
"arches": "archesproject/arches#dev/7.6.x",
"arches_for_science": "archesproject/arches-for-science#dev/2.0.x"
}
```
5. Update urls.py to include the arches-for-science urls
```
urlpatterns = [
path("", include("arches.urls")),
path("", include("arches_for_science.urls")),
path("reports/", include("arches_templating.urls")),
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
```
6. Install the arches application package (models and other data)
```
python manage.py packages -o load_package -a arches_for_science -dev -y
```
7. Start your project
```
python manage.py runserver
```
8. Next cd into your project's app directory (the one with package.json e.g. `$PROJECT_NAME/$PROJECT_NAME/`) install and build front-end dependencies:
```
npm install
npm run build_development
```
125 changes: 13 additions & 112 deletions releases/2.0.0.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,124 +16,25 @@ JavaScript:
none
```

## Installation
### Breaking Changes
Due to changes in how projects and apps are configured in the final release of Arches 7.6.3, there are significant project alterations that necessary to run this version of Arches for Science.

If you are installing Arches for Science for the first time, you can install it as an Arches application into a project or run it directly as an Arches project. Running Arches for Science as a project can provide some convienience if you are a developer contributing to the Arches for Science project. Otherwise, **we strongly recommend running Arches for Science as an Arches Application** within a project because that will allow greater flexibility in customizing your project without the risk of conflicts when upgrading to the next version of Arches for Science.
### Upgrading Arches for Science
1. Start by upgrading your project to run using [Arches 7.6](https://github.com/archesproject/arches/blob/dev/7.6.x/releases/7.6.0.md#upgrading-arches).


### If installing for development
Clone the arches-for-science repo and checkout the latest `dev/x.x.x` branch.
Navigate to the `arches-for-science` directory from your terminal and run:
```
pip install -e .
```

### If installing for deployment, run:
```
pip install arches-for-science
```

`Important`: Installing the arches-for-science app will install Arches as a dependency. This may replace your current install of Arches with a version from PyPi. If you've installed Arches for development using the `--editable` flag, you'll need to re pip install arches after installing arches-for-science

## 2. Project Configuration

1. If you don't already have an Arches project, you'll need to create one by following the instructions in the Arches [documentation](http://archesproject.org/documentation/).
Since Arches for Science uses `Cantaloupe` as its IIIF server, take notice of the
Cantaloupe [installation instructions](https://arches.readthedocs.io/en/stable/developing/advanced/managing-and-hosting-iiif/), too.

2. When your project is ready add "arches_templating", "arches_for_science", and "pgtrigger" to INSTALLED_APPS **below** the name of your project:
```
INSTALLED_APPS = (
...
"my_project_name",
"arches_templating",
"arches_for_science",
"pgtrigger",
)
```

Below the `INSTALLED_APPS` setting add the following setting:
```
INSTALLED_APPS += ("arches.app",)
```

Also add the following lines to settings.py. (Note: ``arches-project create``
before Arches 6.2.6 or 7.5.0 did not create ``RENDERERS``, so you may need to
[add it first](https://github.com/archesproject/arches/pull/10171/files)
before extending it as shown below):
```
FUNCTION_LOCATIONS.append("arches_for_science.pkg.extensions.functions")
TEMPLATES[0]["OPTIONS"]["context_processors"].append("arches_for_science.utils.context_processors.project_settings")
RENDERERS += [
{
"name": "xy-reader",
"title": "XY Data File Reader",
"description": "Use for all instrument outputs with x-y data",
"id": "e93b7b27-40d8-4141-996e-e59ff08742f3",
"iconclass": "fa fa-bolt",
"component": "views/components/cards/file-renderers/xy-reader",
"ext": "txt",
"type": "text/plain",
"exclude": "",
},
]
XY_TEXT_FILE_FORMATS = ["txt"]
X_FRAME_OPTIONS = "SAMEORIGIN"
```

Next ensure arches and arches_for_science are included as dependencies in package.json
```
"dependencies": {
"arches": "archesproject/arches#dev/7.6.x",
2. Update arches-for-science in your project's package.json file:
```
"arches_for_science": "archesproject/arches-for-science#dev/2.0.x"
}
```

Update urls.py to include the arches-for-science urls
```
urlpatterns = [
path("", include("arches.urls")),
path("", include("arches_for_science.urls")),
path("reports/", include("arches_templating.urls")),
] + static(settings.MEDIA_URL, document_root=settings.MEDIA_ROOT)
```

Install the arches application package (models and other data)
```
python manage.py packages -o load_package -a arches_for_science -dev -y
```

Start your project
```
python manage.py runserver
```

Next cd into your project's app directory (the one with package.json e.g. `$PROJECT_NAME/$PROJECT_NAME/`) install and build front-end dependencies:
```
npm install
npm run build_development
```





### Upgrading Arches for Science

If you are running Arches for Science as a project (upgrading from a version prior to AfS v1.1.0), you will need to follow the project upgrade instructions for Arches 7.6.0.

If you are running Arches for Science as an Arches application (using AfS v1.1.0) you will need to do the following:
```
2. Upgrade to Arches 7.6.3
3. Add arches_for_science to your project's dependencies in your pyproject.toml file:
```
pip install --upgrade arches==7.6.3
"arches_for_science>=2.0.0,<2.1.0"
```
3. If you are running Arches on Apache, restart your server:
4. Upgrade to Arches for Science 2.0.0
```
sudo service apache2 reload
pip install --upgrade arches_for_science==2.0.0
```

0 comments on commit 912ee73

Please sign in to comment.