{"id":15716970,"url":"https://github.com/cjpatton/seaice","last_synced_at":"2026-02-14T12:37:11.317Z","repository":{"id":8789751,"uuid":"10480771","full_name":"cjpatton/seaice","owner":"cjpatton","description":" Code for the online YAMZ metadictionary (formerly seaice).","archived":false,"fork":false,"pushed_at":"2015-09-10T06:02:39.000Z","size":2535,"stargazers_count":1,"open_issues_count":5,"forks_count":1,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-10-05T04:01:36.429Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"http://yamz.net","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cjpatton.png","metadata":{"files":{"readme":"README","changelog":null,"contributing":null,"funding":null,"license":"COPYING","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2013-06-04T14:38:48.000Z","updated_at":"2016-05-24T04:38:48.000Z","dependencies_parsed_at":"2022-08-19T15:20:44.044Z","dependency_job_id":null,"html_url":"https://github.com/cjpatton/seaice","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/cjpatton/seaice","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjpatton%2Fseaice","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjpatton%2Fseaice/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjpatton%2Fseaice/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjpatton%2Fseaice/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cjpatton","download_url":"https://codeload.github.com/cjpatton/seaice/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cjpatton%2Fseaice/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29443495,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-14T10:51:12.367Z","status":"ssl_error","status_checked_at":"2026-02-14T10:50:52.088Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-03T21:48:20.585Z","updated_at":"2026-02-14T12:37:11.288Z","avatar_url":"https://github.com/cjpatton.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"This is the README for the YAMZ metadictionary and includes instructions for \ndeploying on a local machine for testing and on Heroku (heroku.com) for a \nscalable production version. These assume a Ubuntu GNU/Linux environment, but \nshould be easily adaptable to any system; YAMZ is written in Python and uses \nonly cross-platform packages. \n  \n  Authored by Chris Patton. Last updated 28 Sep 2014. \n\nYAMZ is formerly known as SeaIce; for this reason, the database tables \nand API are named for SeaIce. \n\n\n\nContents \n========\n \n 0. Prerequites \n     0.1 Repository structure\n \n 1. Configuring a local instance\n     1.1 Postgres authentication\n     1.2 Create the database\n     1.3 Create a role for standard queries\n     1.4 Oauth credentials and app key\n     1.5 N2T persistent identifier credentials\n     1.6 Test the instance\n \n 2. Deploying to Heroku\n     2.1 Heroku-Postgres\n     2.2 Mailgun\n     2.3 Heroku-Scheduler\n     2.4 Making changes\n     2.5 Exporting the dictionary\n\n 3. URL forwarding\n\n 4. Building the docs \n\n\n0. Prerequisites \n================\n\nThe contents of this directory are as follows: \n\n  sea.py . . . . . . . . . . Consolue utility for scoring and classifying\n                             terms and other things. \n\n  ice.py . . . . . . . . . . Web server front end.\n\n  digest.py  . . . . . . . . Console email notification utility.\n\n  requirements.txt . . . . . Heroku package dependencies.\n\n  Procfile . . . . . . . . . Heroku configuration.\n\n  seaice/  . . . . . . . . . The SeaIce Python module. \n\n  html/  . . . . . . . . . . HTML templates, static Javascript and CSS, \n                             including bootstrap.js. \n \n  doc/ . . . . . . . . . . . API documentation and tools for building it. \n\n  .seaice/.seaic_auth  . . . DB credentials, API keys, app key, etc. Note \n                             that these files are just templates and don't\n                             contain actual keys. \n\nBefore you get started, you need to set up a database and some software \npackages. On Ubuntu, grab the follwoing:\n  \n  python-flask . . . . . . . Simple HTTP server.\n\n  postgresql . . . . . . . . We're using PostgreSQL for databse managment. \n\n  python-psycopg2  . . . . . Python API for PostgreSQL.\n\n  python-pip . . . . . . . . Package manager for additional Python \n                             programs. \n\nWe need to download a package from pip that handles configuration files\nnicely. Do: \n\n  $ sudo pip install configparser flask-login flask-Oauth \n    python-dateutil urlparse\n\n\n0.1 Repository structure\n========================\n\nThe 'master' branch contains all the code to deploy locally or on heroku. \nThis directory. To deploy, create a local branch called \"deploy_keys\" and \nedit .seaice .seaice_auth with actual API and app keys. Then push to \nheroku with `git push heroku deploY_keys:master`. See section 2 for more \non heroku. NEVER PUSH THIS BRANCH TO GITHUB. \n\n\n\n1. Configuring a local instance \n===============================\n\nTo start, we'll set up a database in postgres. First, we need to do some \nconfiguration. Postgres requires an administrative user called 'postgres'. \nIt may be a good idea to create a SeaIce user (called \"role\" in postgres \njargin) with read/ write access granted on the tables. First, set postgres' \npassword: \n\n  $ sudo -u postgres psql template1\n  template1=# alter uesr postgres with encrypted password 'PASS';  \n  template1=# \\q [quit] \n\n\n1.1 Posgres authentication\n==========================\n\nNow configure the authentication method for postgres and all other users \nconnecting locally. In /etc/postgresql/9.1/main/pg_hba.conf, change \"peer\" \nin line\n\n local   all         postgres                          peer\n\nto \"md5\" for the administrative account and local unix domain socket \nconnections. Next, we want to only be able to connect to the database from \nthe local machine. In /etc/postgresql/9.1/main/postgresql.conf, uncomment the \nline\n\n listen_addresses = 'localhost'\n\nAfter you've done this, you need to restart the postgres server:\n\n  $ sudo service postgresql restart\n\n\n1.2 Create the database\n=======================\n\nFinally, log back into postgres to create the database:\n\n  $ sudo -u postgres psql\n  postgres=# create database seaice with owner postgres;\n  \n(Using unique, completely random passwords is a good idea here.) Next, \ncreate a configuration file for the database and user account you set up. \nCreate a file called `.seaice` like: \n\n  [default]\n  dbname = seaice\n  user = postgres\n  password = PASS\n\nIMPORTANT NOTE: A template of this file is provided in the github\nrepository. This file should remain secret and must not be published. \nSet the correct file permissions with: \n\n  $ chmod 600 `.seaice`\n\nThis file is used by the SeaIce DB connector to grant access to the database.\nTo initialize the DB schema and tables, type:\n  \n  $ ./sea.py --init-db --config=.seaice\n\n\n1.3 Create a role for standard queries\n======================================\n\nAt this point, it's suggested that you set up a user standard read/write \npermssions on the table (no DROP, CREATE, GRANT, etc.) for most of the \ndatabase queries. Note that this isn't applicable in Heroku; the postgres\ninterface there doesn't allow you to control user views. \n  \n  postgres=# create user contributor with encrypted password 'PASS';\n  postgres=# \\c seaice;\n  postgres=# grant select, insert, update, delete on all tables in \n             schema SI, SI_Notify to contributor;\n\nAdd the configuuration to `.seaice`: \n\n  [contributor]\n  dbname = seaice\n  user = contributor\n  password = PASS\n\nThe web user interface creates a database connection pool with the \nsame role. You can specify this on the command line: \n\n  $ ./ice.py --role=contributor --config=.seaice\n\n'--role' defaults to 'default'. \n\n\n1.4 Oauth credentials and app key\n=================================\n\nYAMZ uses Google for third party authentication (OAuth-2.0) management of \nlogins. Visit https://console.developers.google.com to set this service up \nfor your instance. Navigate to \"APIs \u0026 auth\" -\u003e \"Credentials\" and click \n\"Create new client ID\". For local configuration: \n \n Application type . . . . . . . . . . . . Web application\n Authorized javascript origins  . . . . . http://localhost:5000 \n Authorized redirect URI  . . . . . . . . http://localhost:5000/authorized \n\nYou'll create a new client ID for your heroku instance. (See section 2.) \nNext, create a configuration file called `.seaice_auth` with the appropriate \nclient ID's and secret keys. For instance, you may have credentials for \n'http://localhost:5000', as well as a dpeloyment on heroku: \n\n  [dev]\n  google_client_id = 000-fella.apps.googleusercontent.com\n  google_client_secret = SECRET1\n  app_secret = SECRET2\n\n  [heroku]\n  google_client_id = 000-guy.apps.googleusercontent.com\n  google_client_secret = SECRET3\n  app_secret = SECRET4\n\nIMPORTANT NOTE: A template of this file is provided in the github\nrepository. This file should remain secret and must not be published. \nWe provide the template, since heroku requires a commited file. \n\nFor conveniance, this file will also keep the Flask app's secret key. For \nthis key, enter a long, random string of characters. Finally, set the correct \nfile permissions with: \n\n  $ chmod 600 `.seaice_auth`\n\n\n1.5 N2T persistent identifier credentials\n========================================= \n\nA third-party URI resolver (maintianed by John Kunze et al.) is now an \nintegrated part of YAMZ. It is therefore necessary to provide a minter \npassword for API access to this web service. Include a line in .seaice_auth \nfor every view:\n \n minter_password = PASS\n\n\n1.6 Test the instance\n=====================\n\nFirst, create the database schema: \n\n  $ ./sea --config=.seaice --init-db\n\nStart the local server with: \n \n  $ ./ice.py --config=.seaice --deploy=dev\n\nIf all goes well, you should be able to navigate to your server by typing \n'http://localhost:5000' in the address bar. To verify that you've set up \nGoogle Oauth-2.0 correctly, try logging in. This will create an account.\nTry adding a new term, modifying and deleting a term, and commenting on \ntermss. To classify a term, do: \n\n  $ ./sea.py --config=.seaice --classify-terms\n\n\n\n2. Deploying to Heroku\n======================\n\nThe YAMZ prototype is currently hosted at http://yamz.herokuapp.com. \nHeroku is a cloud-computing service which allows users to host web-based\nsoftware projects. Heroku is scalable for a price; however, we can \nstill achieve quite a bit without spending money. We have access to a \nsmall Postgres database, can shedule jobs, use a variety of packages \n(all we need are available), and deploy easily with Git. It is however\nimpossible to set up DB roles. Also, we can't assume persistent \naccess to the filesystem. \n\nTo begin, you need to setup an account with Heroku and download their software. \n(It's nothing major, just some tools for running commands, interacting with \nthe database, etc.) Visit http://www.heroku.com. \n\nHeroku requires a couple additional configuration files and some small\ncode changes. The additional files are:\n\n  Procfile . . . . . . . specifies the commands that start web server, as \n                         well as periodic jobs. \n\n  requirements.txt . . . a list of packages required by our software that \n                         Heroku needs to make available. These are \n                         available via pip.\n\nI used the following tutorial: https://devcenter.heroku.com/articles/python\nto set these up. Note that these steps have already been done; once you've\nset up your heroku account, you're ready to deploy. \n\nThe recommended best practice for managing your heroku instance is to set up\na local branch called 'deploy_keys' based on 'master'. In this branch, edit \n.seaice_auth to contain actual API and app keys. NOTE: IT IS CRITICAL THAT \nYOU DON'T PUSH THIS BRANCH TO GITHUB. Publishing these secrets comprimises \nthe security of the entire app.\n\nLogin via the heroku website and create a new app. (Suppose we've named it\n\"fella\".) Navigate to the directory containing the cloned repository. Create\nand checkout the branch 'deploy_keys'. \n\n  $ heroku login\n  $ heroku git:remote -a fella\n  $ git push heroku deploy_keys:master\n\nThis creates a \"slug\" containing our code and its dependencies. To get the web \napp running, we'll now need to set up a database and a couple heroku backend \nservices. \n\n\n2.1 Heroku-Postgres\n===================\n\nHeroku-Postgres is a scalable DB interface for heroku apps. Follow the \nfollowing tutorial to set this up: \nhttps://devcenter.heroku.com/articles/heroku-postgresql#connection-in-python\n\nThe 'master' branch is set up to use either a local postgres database server\nor Heroku-Postgres. The location of the DB in the \"cloud\" is specified by the \nenvironment variable \"DATABASE_URL\". Using 'sea' or 'ice' with '--config=heroku'\nwill force SeaIce to use this variable to connect to the DB. (Note this is the \ndefault.) Heroku-Postgres doesn't allow you to create roles, so '--role' will \nbe ignored and the default will be used. To create the database schema: \n\n  $ heroku run python sea.py --init-db\n\n\n2.2 Mailgun\n===========\n\nYAMZ provides an email notification service for users who opt in. A utility \ncalled 'digest' collects for each user all notifications that haven't previously \nbeen emailed into a single digest. The code uses a heroku backend app called \nMailgun for SMTP service. To set this up, simply type \n\n  $ heroku addons:add mailgun\n\nThe code uses environment variables \"MAILGUN_SMTP_LOGIN\" and \n\"MAILGUN_SMTP_PASSWORD\" to connect to Mailgun. To send out notifications, \ntype: \n\n  $ heroku run python digest.py \n\n\n2.3 Heroku-Scheduler\n====================\n\nThere are two periodic jobs that need to be scheduled in YAMZ: the term \nclassifier and the email digest. To set this up, do: \n  \n  $ heroku addons:add scheduler\n  $ heroku addons:open scheduler\n\nThe second command will take you to the web interface for the scheduler. Add\nthe following two jobs: \n\n  \"python sea.py --classify-terms\" . . . . . every 10 minutes\n  \"python digest.py\" . . . . . . . . . . . . once per day\n\n\n2.4 Making changes\n==================\n\nDeploying changes to heroku is made very easy with Git. Suppose we have changes\nto 'master' that we want to push to heroku. First checkout the already created\nlocal 'deploy_keys' branch:\n  \n $ git checkout deploy_keys\n $ git merge master\n $ git push heroku deploy_keys:master\n\n\n2.5 Exporting the dictionary\n============================\n\nThe SeaIce API includes queries for importing and exporting database tables \nin JSON formatted objects. This could be used to backup the entire database.\nNote however that imports must be done in the proper order in order to satisfy\nforeign key constratins. To back up the dictionary, do: \n\n  $ heroku config | grep DATABASE_URL\n  DATABASE_URL: \u003cwhatever\u003e\n  $ export DATABASE_URL=\u003cwhatever\u003e \n  $ ./sea.py --config=heroku --export=Terms \u003eterms.json\n\n\n\n3. URL forwarding\n=================\n\nThe current stable implementation of YAMZ is redirected from http://yamz.net. \nSetting this up takes a bit of doing. The following instructions are synthsized\nfrom http://lifesforlearning.com/heroku-with-godaddy/ for redirecting a domain\nname managed by GoDaddy to a Heroku app.\n\nLaunch the \"Domains\" app on GoDaddy. Under \"Forward Domain\" for the appropriate\ndomain (let's call it \"fella.org\"), add the following settings:\n \n Forward to . . . . . . . . . . . . . . . . . . . . http://www.fella.org\n Redirect type  . . . . . . . . . . . . . . . . . . 301 (Permanent)\n Forward settings . . . . . . . . . . . . . . . . . Forward only \n Update nameservers and DNS settings \n           to support this change . . . . . . . . . yes\n\nNext, under \"Manage DNS\", remove all entries except for 'A (Host)' and 'NS \n(Nameserver)', and add the following under 'CName (Alias)': \n\n Record type  . . . . . . . . . . . . . . . . . CNAME (Alias)\n Host . . . . . . . . . . . . . . . . . . . . . www\n Points to  . . . . . . . . . . . . . . . . . . http://fella.herokuapp.com\n TTL  . . . . . . . . . . . . . . . . . . . . . 1 Hour\n\nNext, change the IP address for entry '@' under 'A (Host)' to 50.63.202.31. \n\nThat's it for DNS configuration. The last thing we need to do is modify the \nredirect URLS in the Google Oauth API. Edit the authorized javascript origins \nand redirect URI by replacing \"fella.herokuapp.com\" with \"fella.org\" and \nsave. \n\nIt can take a couple hours to a day for your DNS settings to propogate. Once \nit's done, you can navigate to YAMZ by typing \"fella.org\" into your browser.\nTry logging in to verify that the Oauth settings are also correct. \n\n\n\n4. Building the docs \n====================\n\nThe seaice package is autodoc'ed using python-sphinx. To install on Ubuntu:\n\n  $ sudo apt-get install python-sphinx\n\nThe directory doc/sphinx includes a Makefile for exporting the docs to \nvarious media. For example, \n\n  make html\n  make latex\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcjpatton%2Fseaice","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcjpatton%2Fseaice","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcjpatton%2Fseaice/lists"}