Ocelot-Social/gitbook-docs/search_plus_index.json

{"./":{"url":"./","title":"Introduction","keywords":"","body":"Ocelot.Social ocelot.social is free and open source software program code to run social networks. Its development is supported by a community of programmers and interested network operators. Our goal is to enable people to participate fairly and equally in online social networks. The equality of opportunity applies both to the fundamental equality of all people and to the possibility of letting their diverse voices be heard. We therefore consider it desirable that operators offer such networks so that people can choose where they want to be on the move. At the same time, it should be possible in the future to link these networks with each other (ActivityPub, Fediverse), so that users can also connect with people from other networks - for example by making friends or following posts or other contributions. In other words, we are interested in a network of networks and in keeping the data as close as possible to the user and the operator they trusts. Screenshots Check out more screenshots here. Features Ocelot.social networks feature: user accounts user roles posts and comments groups maps search filters and more … Check out the full feature list. User Guide and Frequently Asked Questions In the wiki you can find more information. User Guide Frequently Asked Questions Demo Try out our live demo network, see here. Help us If you're wondering how you could help, there are plenty of ways, e.g.: Spread the good word about ocelot.social to make it more popular: Add the link ocelot.social to your website. Give ocelot.social a Like at https://alternativeto.net/software/ocelot-social/. Star our project on GitHub at https://github.com/Ocelot-Social-Community/Ocelot-Social/. Promote it on your social networks. Tell your friends about it by word-of-mouth. Write a press article on ocelot.social or contact the editorial office of your local newspage or radio station. Take a good first issue or issues that need help. Make sure to read CONTRIBUTING.md first though. Testing and reporting bugs. Translating: Please contact us. Reviewing and testing pull requests. Donate Your donation is very welcome and helps to enhance and improve the network. This software is mostly developped and maintained by the association busFaktor() e.V.. Please support us with a donation to busFaktor() e.V.. Thanks a lot! ❤️ Contact Are you interested in operating your own ocelot.social network or becoming a user? Please contact us here: hello@ocelot.social Discord For Developers and Contributors Introduction Have a look into our short video: ocelot.social - GitHub - Developer Welcome - Tutorial (english) Directory Layout There are three important directories: Backend runs on the server and is a middleware between database and frontend Frontend is a server-side-rendered and client-side-rendered web frontend Cypress contains end-to-end tests and executable feature specifications In order to setup the application and start to develop features you have to setup frontend and backend. There are two approaches: Local installation, which means you have to take care of dependencies yourself. Or Install everything through Docker which takes care of dependencies for you. Installation Clone the Repository Clone the repository, this will create a new folder called Ocelot-Social: Using HTTPS: $ git clone https://github.com/Ocelot-Social-Community/Ocelot-Social.git Using SSH: $ git clone git@github.com:Ocelot-Social-Community/Ocelot-Social.git Change into the new folder. $ cd Ocelot-Social Live Demo And Developer Logins Try out our deployed development environment. Visit our staging networks: central staging network: stage.ocelot.social Login Logins for the live demos and developers (local developers after the following installations) in the browser: email password role user@example.org 1234 user moderator@example.org 1234 moderator admin@example.org 1234 admin Docker Installation Docker is a software development container tool that combines software and its dependencies into one standardized unit that contains everything needed to run it. This helps us to avoid problems with dependencies and makes installation easier. General Installation of Docker There are several ways to install Docker CE on your computer or server. install Docker Desktop on macOS install Docker Desktop on Windows install Docker CE on Linux Check the correct Docker installation by checking the version before proceeding. E.g. we have the following versions: $ docker --version Docker version 18.09.2 $ docker-compose --version docker-compose version 1.23.2 Start Ocelot-Social via Docker-Compose Prepare ENVs once beforehand: # in folder webapp/ $ cp .env.template .env # in folder backend/ $ cp .env.template .env For Development: # in main folder $ docker-compose up For Production: # in main folder $ docker-compose -f docker-compose.yml up This will start all required Docker containers.Make sure your database is running on http://localhost:7474/browser/. Prepare database once before you start by running the following command in a second terminal: # in main folder while docker-compose is up $ docker compose exec backend yarn run db:migrate init $ docker compose exec backend yarn run db:migrate up Then clear and seed database by running the following command as well in the second terminal: # in main folder while docker-compose is up $ docker-compose exec backend yarn run db:reset $ docker-compose exec backend yarn run db:seed For a closer description see backend README.md.For a full documentation see SUMMARY. Local Installation For a full documentation see SUMMARY. Contributing Choose an issue (consider our label good-first-issue) and leave a comment there. We will then invite you to join our volunteers team. To have the necessary permission to push directly to this repository, please accept our invitation to join our volunteers team, you will receive via the email, Github will send you, once invited. If we did not invite you yet, please request an invitation via Discord. We are happy if you fork our repository, but we don't recommend it for development. You do not need a fork. Clone this repository locally as described above, create your branch named -, add your code and push your branch to this repository. Then create a PR by comparing it to our master. Please run the following commands before you push: # in folder backend/ $ yarn lint --fix $ yarn test # in folder webapp/ $ yarn lint --fix $ yarn locales --fix $ yarn test Check out our contribution guideline, too! Developer Chat Join our friendly open-source community on Discord :heart_eyes_cat: Just introduce yourself at #introduce-yourself and mention a mentor or @@Mentors to get you onboard :neckbeard: We give write permissions to every developer who asks for it. Just text us on Discord. Deployment Deployment methods can be found in the Ocelot-Social-Deploy-Rebranding repository. The only deployment method in this repository for development purposes as described above is docker-compose. Technology Stack VueJS NuxtJS GraphQL NodeJS Neo4J For Testing Cypress Storybook Jest Vue Test Utils ESLint Attributions Locale Icons made by Freepik from www.flaticon.com is licensed by CC 3.0 BY. Browser compatibility testing with BrowserStack. License See the LICENSE file for license rights and limitations (MIT). "},"edit-this-documentation.html":{"url":"edit-this-documentation.html","title":"Edit this Documentation","keywords":"","body":"Edit this Documentation Find the table of contents for this documentation on GitHub and navigate to the file you need to update. Click on the edit pencil on the right side directly above the text to edit this file on your fork of Human Connection (HC). You can see a preview of your changes by clicking the Preview changes tab aside the Edit file tab. If you are ready, fill in the Propose file change at the end of the webpage. After that you have to send your change to the HC basis with a pull request. Here make a comment which issue you have fixed. (If you are working on one of our open issues please include the number.) Markdown your documentation To design your documentation see the syntax description at GitBook: https://toolchain.gitbook.com/syntax/markdown.html Some quick Examples Headlines # Main headline ## Smaller headlines ### Small headlines Tabs {% tabs %} {% tab title=\"XXX\" %} XXX {% endtab %} {% tab title=\"XXX\" %} XXX {% endtab %} … {% endtabs %} Commands ``` (for text highlighting) XXX ``` Links [XXX](https://XXX) Screenshots or other Images ![XXX](https://XXX) Hints For ToDos {% hint style=\"info\" %} TODO: XXX {% endhint %} Host The Screenshots Often we need screenshots to explain things. Host On Ocelot-Social GitHub repository TODO: How to host on Ocelot-Social GitHub repository ... Quick Solution To quickly host the screenshots go to: https://imgur.com. There click the green button New post. Drag the image into the appropriate area. Right click on it and choose kind of Open link in new tab. Copy the URL and paste it were you need it. Screenshot modification Add an arrow or some other marking stuff macOSWindowsLinuxIn the Preview AppGot to: Menu + Tools (GER: Werkzeuge) + Annotate (GER: Anmerkungen) + etc. "},"neo4j/":{"url":"neo4j/","title":"Neo4J","keywords":"","body":"Neo4J Human Connection is a social network. Using a graph based database which can model nodes and edges natively - a network - feels like an obvious choice. We decided to use Neo4j, the currently most used graph database available. The community edition of Neo4J is Free and Open Source and we try our best to keep our application compatible with the community edition only. Installation With Docker Run: docker-compose up You can access Neo4J through http://localhost:7474/ for an interactive cypher shell and a visualization of the graph. Installation Without Docker Install the community edition of Neo4j along with the plugin Apoc on your system. To do so, go to releases, choose \"Community Server\", download the installation files for you operation system and unpack the files. Download Neo4j Apoc and drop the .jar file into the plugins folder of the just extracted Neo4j-Server. Then make sure to allow Apoc procedures by adding the following line to your Neo4j configuration (conf/neo4j.conf): dbms.security.procedures.unrestricted=apoc.* Alternatives You can download Neo4j Desktop and run locally for development, spin up a hosted Neo4j Sandbox instance, run Neo4j in one of the many cloud options, spin up Neo4j in a Docker container, on Arch linux you can install neo4j-community from AUR or on Debian-based systems install Neo4j from the Debian Repository. Just be sure to update the Neo4j connection string and credentials accordingly in backend/.env. Start Neo4J and confirm the database is running at http://localhost:7474. Commands Here we describe some rarely used Cypher commands for Neo4j that are needed from time to time: Index And Constraint Commands If indexes or constraints are missing or not set correctly, the browser search will not work or the database seed for development will not work. The indexes and constraints of our database are set in backend/src/db/migrate/store.js. This is where the magic happens. It's called by our prod:migrate init command. This command initializes the Admin user and creates all necessary indexes and constraints in the Neo4j database. Calls in development Locally without Docker: # in backend folder $ yarn prod:migrate init Locally with Docker: # in main folder $ docker compose exec backend yarn prod:migrate init Calls in production Locally with Docker: # in main folder $ docker compose exec backend /bin/sh -c \"yarn prod:migrate init\" On a server with Kubernetes cluster: # tested for one backend replica # !!! be aware of the kubectl context !!! $ kubectl -n default exec -it $(kubectl -n default get pods | grep ocelot-backend | awk '{ print $1 }') -- /bin/sh -c \"yarn prod:migrate init\" Cypher commands to show indexes and constraints # in browser command line or cypher shell # show all indexes and constraints $ :schema # show all indexes $ CALL db.indexes(); # show all constraints $ CALL db.constraints(); Cypher commands to create and drop indexes and constraints # in browser command line or cypher shell # create indexes $ CALL db.index.fulltext.createNodeIndex(\"post_fulltext_search\",[\"Post\"],[\"title\", \"content\"]); $ CALL db.index.fulltext.createNodeIndex(\"user_fulltext_search\",[\"User\"],[\"name\", \"slug\"]); $ CALL db.index.fulltext.createNodeIndex(\"tag_fulltext_search\",[\"Tag\"],[\"id\"]); # drop an index $ DROP CONSTRAINT ON ( image:Image ) ASSERT image.url IS UNIQUE # drop all indexes and constraints $ CALL apoc.schema.assert({},{},true) YIELD label, key RETURN * ; "},"backend/":{"url":"backend/","title":"Backend","keywords":"","body":"Backend Installation with Docker Run the following command to install everything through docker. The installation takes a bit longer on the first pass or on rebuild ... # in main folder $ docker-compose up # or # rebuild the containers for a cleanup $ docker-compose up --build Wait a little until your backend is up and running at http://localhost:4000/. Installation without Docker For the local installation you need a recent version of Node (>= v16.19.0). We are using v19.4.0 and therefore we recommend to use the same version (see some known problems with more recent node versions). You can use the node version manager nvm to switch between different local Node versions: # install Node $ cd backend $ nvm install v19.4.0 $ nvm use v19.4.0 Install node dependencies with yarn: # in main folder $ cd backend $ yarn install # or just $ yarn # or just later on to use version of \".nvmrc\" file $ nvm use && yarn Copy Environment Variables: # in backend/ $ cp .env.template .env Configure the new file according to your needs and your local setup. Make sure a local Neo4J instance is up and running. Start the backend for development with: # in backend/ $ yarn run dev or start the backend in production environment with: # in backend/ $ yarn run start For e-mail delivery, please configure at least SMTP_HOST and SMTP_PORT in your .env configuration file. Your backend is up and running at http://localhost:4000/ This will start the GraphQL service (by default on localhost:4000) where you can issue GraphQL requests or access GraphQL Playground in the browser. More details about our GraphQL playground and how to use it with ocelot.social can be found here. Database Indexes and Constraints Database indexes and constraints need to be created and upgraded when the database and the backend are running: DockerWithout Docker# in main folder while docker-compose is running $ docker exec backend yarn run db:migrate init # only once: init admin user and create indexes and constraints in Neo4j database # for development $ docker compose exec backend yarn prod:migrate init # in production mode use command $ docker compose exec backend /bin/sh -c \"yarn prod:migrate init\" # in main folder with docker compose running $ docker exec backend yarn run db:migrate up # in folder backend/ while database is running # make sure your database is running on http://localhost:7474/browser/ yarn run db:migrate init # in backend/ with database running (In docker or local) yarn run db:migrate up Seed Database If you want your backend to return anything else than an empty response, you need to seed your database: DockerWithout DockerIn another terminal run:# in main folder while docker-compose is running $ docker exec backend yarn run db:seed To reset the database run:# in main folder while docker-compose is running $ docker exec backend yarn run db:reset # you could also wipe out your neo4j database and delete all volumes with: $ docker-compose down -v # if container is not running, run this command to set up your database indexes and constraints $ docker exec backend yarn run db:migrate init # And then upgrade the indexes and const $ docker exec backend yarn run db:migrate up Run:# in backend/ while database is running $ yarn run db:seed To reset the database run:# in backend/ while database is running $ yarn run db:reset Data migrations Although Neo4J is schema-less,you might find yourself in a situation in which you have to migrate your data e.g. because your data modeling has changed. DockerWithout DockerGenerate a data migration file:# in main folder while docker-compose is running $ docker-compose exec backend yarn run db:migrate:create your_data_migration # Edit the file in ./src/db/migrations/ To run the migration:# in main folder while docker-compose is running $ docker exec backend yarn run db:migrate up Generate a data migration file:# in backend/ $ yarn run db:migrate:create your_data_migration # Edit the file in ./src/db/migrations/ To run the migration:# in backend/ while database is running $ yarn run db:migrate up Testing Beware: We have no multiple database setup at the moment. We clean the database after each test, running the tests will wipe out all your data! DockerWithout DockerRun the unit tests:# in main folder while docker-compose is running $ docker exec backend yarn run test Run the unit tests:# in backend/ while database is running $ yarn run test "},"backend/graphql.html":{"url":"backend/graphql.html","title":"GraphQL","keywords":"","body":"GraphQL with Apollo GraphQL is a data query language which provides an alternative to REST and ad-hoc web service architectures. It allows clients to define the structure of the data required, and exactly the same structure of the data is returned from the server. Middleware keeps resolvers clean A well-organized codebase is key for the ability to maintain and easily introduce changes into an app. Figuring out the right structure for your code remains a continuous challenge - especially as an application grows and more developers are joining a project. A common problem in GraphQL servers is that resolvers often get cluttered with business logic, making the entire resolver system harder to understand and maintain. GraphQL Middleware uses the middleware pattern (well-known from Express.js) to pull out repetitive code from resolvers and execute it before or after one of your resolvers is invoked. This improves code modularity and keeps your resolvers clean and simple. "},"backend/neo4j-graphql-js.html":{"url":"backend/neo4j-graphql-js.html","title":"neo4j-graphql-js","keywords":"","body":"neo4j-graphql.js We use an npm package called neo4j-graphql-js as a cypher query builder. This library also generates resolvers for graphql queries, unless we implement them ourselves. Debugging As you can see in their documentation it is possible to log out the generated cypher statements. To do so, run the backend like this: DEBUG=neo4j-graphql-js yarn run dev "},"webapp/":{"url":"webapp/","title":"Webapp","keywords":"","body":"Webapp Installation For preparation we need Node and recommend to use node version manager nvm to switch between different local Node versions: # install Node $ cd webapp $ nvm install v19.4.0 $ nvm use v19.4.0 Install node dependencies with yarn: # install all dependencies $ cd webapp $ yarn install # or just $ yarn # or just later on to use version of \".nvmrc\" file $ nvm use && yarn Copy: # in webapp cp .env.template .env Configure the files according to your needs and your local setup. Build for Development # serve with hot reload at localhost:3000 $ yarn dev Build for Production # build for production and launch server $ yarn build $ yarn start Run tests We ensure the quality of our frontend code by using ESLint for checking our JavaScript code Jest and Vue Test Utils to unit test our components Storybook to document and manually test our components in an isolated playground For more information see our frontend testing guide. Use these commands to run the tests: With DockerWithout DockerAfter starting the application following the above guidelines, open new terminal windows for each of these commands:# run eslint $ docker-compose exec webapp yarn lint # run unit tests $ docker-compose exec webapp yarn test # start storybook $ docker-compose exec webapp yarn storybook You can then visit the Storybook playground on http://localhost:3002After starting the application following the above guidelines, open new terminal windows and navigate to the /webapp directory for each of these commands:# run eslint in /webapp (use option --fix to normalize the files) $ yarn lint # run unit tests in /webapp $ yarn test # run locales in /webapp (use option --fix to sort the locales) $ yarn locales # start storybook in /webapp $ yarn storybook You can then visit the Storybook playground on http://localhost:3002 Maintenance Mode For installing and running the maintenance mode see Maintenance Mode. Styleguide Migration We are currently in the process of migrating our styleguide components and design tokens from the Nitro Styleguide into the main ocelot.social repository and refactoring our components in the process. During this migration, our new components will live in a _new/ folder to separate them from the old, yet untouched components. Folder Structure The folder structure we are following is prescribed by Nuxt.js: assets contains icons, images and logos in svg format and all shared SCSS files such as tokens components separated into two sub-folders: generic are the generic building blocks of the app – small, reusable and usually not coupled to state features are composed of components but tied to a particular function of the app (e.g. comment or post) layouts can use components to create layout templates for pages pages are the entry points for all routes in the app and are composed of layouts, features and components "},"webapp/components.html":{"url":"webapp/components.html","title":"Components","keywords":"","body":"Components – Code Guidelines We adhere to the single responsibility principle Each component does exactly one job. The goal is to end up with many small components that are: easy to understand easy to maintain easy to reuse How do you decide what is a separate component? Try to describe what it does in one sentence! When you find yourself using and and or the code you are talking about should probably be split up into two or more components. On the other hand, when something is easily expressed in a few lines of HTML and SCSS and not likely to be reused this is a good indicator that it should not go into a separate component. We compose with components Usually pages use layouts as templates and will be composed of features. features are composed of components, the smallest building blocks of the app. The further down we go in this hierarchy the simpler and more generic the components become. Here is an example: The index page is responsible for displaying a list of posts. It uses the default layout and the PostList feature. The PostList feature uses a List component to render PostTeaser features. The PostTeaser feature consists of a LayoutCard wrapped around a CardImage, CardTitle and CardContent component. The index page is unique in the app and will never be reused. The PostList knows it is handling post data and can therefore not be used for anything else – but it can display posts on the index as well as the user page. The Card on the other hand does not care about the type of data it needs to handle. It just takes whatever it receives and renders it in a certain way, so it can be reused throughout the app for many different features. We use two-word names We follow the W3C rules for naming custom elements as suggested in the Vue.js docs to differentiate our own components from regular HTML elements in our templates. Names should also be meaningful and unique to avoid confusion and code duplication, and also not too long to make them readable. Therefore: aim for two-word names, such as layout-card, post-list or post-teaser. Recommended reads For a deeper dive into the WHY and HOW have a look at the following resources which the above guidelines are based on: Atomic design CDD – component based design Vue.js component styleguide "},"webapp/html.html":{"url":"webapp/html.html","title":"HTML","keywords":"","body":"HTML – Code Guidelines We write semantic markup We avoid using divs and spans and try to choose more meaningful HTML elements instead. If unsure which element to use this list by MDN can be of help. Why? semantic markup is crucial for accessibility it makes the code more readable for other developers it benefits our SEO For more background see this article. This doesn’t mean you can’t ever use a div – just think twice before you do! We write as little HTML as possible – and as much as necessary HTML is used to structure content on the page and should therefore reflect its complexity. Not more and not less. Most content does not require deep nesting of HTML elements – if you find yourself wrapping container around container or adding an element just to correctly position another element on the page this calls for the use of CSS instead! Why? deep nesting makes it hard to understand, style and maintain components it can lead to performance issues Recommended reads For a deeper dive into the WHY and HOW have a look at the following resources: HTML: a good basis for accessibility Why, how, and when to use semantic HTML and ARIA "},"webapp/scss.html":{"url":"webapp/scss.html","title":"SCSS","keywords":"","body":"SCSS - Code Guidelines We use classes over tags and ids Never apply styles to tags or ids – use classes instead! Why? HTML tags are responsible for the document structure, not the looks targeting HTML tags comes with performance issues ids are responsible for identifying a unique element, not for styling it ids have higher specificity than classes and therefore don't play well together classes can be combined and reused while ids are unique For more background see the following articles on why not to style tags and why not to style ids. We use design tokens instead of magic numbers In order to achieve a consistent look and feel we use a set of pre-defined design tokens to style our components, for example colors, sizes and box-shadows. These tokens are stored as SCSS variables and reused throughout the app. So, instead of typing pixel values or hex codes make sure you use design tokens such as height-header or color-input-border. We name our classes after components Our SCSS styles live within the corresponding component (see the Vue.js docs for single-file components for reference) and should therefore carry the same unique name. Why? it clearly ties the styles to the one component having unique class names means styles will not be accidentally overwritten in other files we can avoid using scoped CSS which comes with performance caveats We use variants instead of overriding styles Components will sometimes need to look different depending on the context in which they are used – a button might for example be green when it represents a call to action and red when it triggers a destructive action. Rather than making the rounded-button component green by default and then overriding the color for, say, the delete-account action – use variants! Pass the rounded-button a prop, such as color: danger, and then apply the respective variant class. Name variant classes with a dash prefix, such as -danger, then target them like this: .rounded-button { /* other css styles */ &.-danger { color: $color-danger; } } We style within the component, we position when we use it In order to make components truly reusable it is important to limit their styles to, well, their actual styling. What color are they, how big is the text, what happens on hover, do they have a rounded border – all that is part of it. Margins, alignment and positioning on the other hand need to be defined in the parent because the same component might sometimes be aligned to the left, sometimes to the right and sometimes float above other content. For more details see the rscss guidelines. To do that, use the child selector, like this: .login-form { /* other css styles */ > .rounded-button { margin: $margin-small; justify-self: flex-end; } } A special case are dimensions like width and height. If it is important that a component always has the same dimensions (the height of a button should be consistent, for example) define it within the component itself, if a component should have flexible dimensions (a card, for example, could stretch over the whole screen in one place and be limited to a certain width in another) define the dimensions in the parent. Recommended reads For a deeper dive into the WHY and HOW have a look at the following resources which the above guidelines are based on: rscss – reasonable system for css stylesheet structure itcss – inverted triangle architecture for css "},"webapp/vue.html":{"url":"webapp/vue.html","title":"Vue","keywords":"","body":"Vue – Code Guidelines We use single-file components Each component lives in a single file, containing: its template (the DOM structure) its script (including props, data and methods among other things) its style (defining the look of the component) See the Vue.js docs for more details. Placed in the same folder are also: the test file (e.g. MyComponent.spec.js) the storybook file (e.g. MyComponent.story.js) We use typed props Vue.js allows us to define component props either as strings or as objects (with type and default or required values). Always go for the second option! Also: only (and always!) define a default for props that are not required. Why? it makes our code more robust – a warning will be shown when passing a wrong prop type it clearly defines the component API and tells other developers how to use it It is as easy as writing: props: { title: { type: String, required: true, }, image: { type: String, default: 'human-connection-logo.png', }, } For more complex use cases see the official Vue.js documentation. We use shorthands For better readability we prefer :something over v-bind:something @click over v-on:click #slotSame over v-slot:slotName #default over v-slot Read more in the official Vue.js docs (for slots) Recommended reads The Vue.js component style guide offers a whole list of best-practices for writing Vue components. "},"testing.html":{"url":"testing.html","title":"Testing Guide","keywords":"","body":"Testing Guide End-to-End Testing To test all the pieces together, from the user perspective, we use integration tests. They also show if the the backend and the frontend are working as expected in conjunction and also if the browser likes our app. more... Component Testing Individual Vue Components should also be documented and tested properly. This guarantees that they are reusable and the api gets more solid in the process. more... Unit Testing Expecially the Backend relies on Unit Tests, as there are no Vue Components. more... "},"cypress/":{"url":"cypress/","title":"End-to-end tests","keywords":"","body":"End-to-End Testing Setup with docker Are you running everything through docker? You're so lucky you don't have to setup anything! Just: $ docker-compose up Setup without docker To start the services that are required for cypress testing manually. You basically need the whole setup to run: backend webapp neo4j Navigate to the corresponding folders and start the services. Install cypress Even if the required services for testing run via docker, depending on your setup, the cypress tests themselves run on your host machine. So with our without docker, you would have to install cypress and its dependencies first: # in the root folder / $ yarn install Open Interactive Test Console The interactive cypress test console allows to run tests and have visual feedback on that. The interactive cypress environment also helps at debugging the tests, you can even time travel between individual steps and see the exact state of the app. To use this feature run: $ yarn cypress:open Run cypress To run cypress without the user interface: $ yarn cypress:run This is used to run cypress in CI or in console Write some Tests Check out the Cypress documentation for further information on how to write tests: Write-a-simple-test "},"webapp/testing.html":{"url":"webapp/testing.html","title":"Frontend tests","keywords":"","body":"Component Testing Linting We use ESLint to make sure all developers follow certain code guidelines when writing JavaScript. Most code editors offer an ESLint plugin which helps detect mistakes already while you are writing code. To run the linter manually before pushing up new code type yarn lint into your terminal. Most minor issues can be fixed automatically with the command yarn lint --fix. Unit tests We write unit tests with the help of Jest and Vue Test Utils to make sure our components work in the way they should. In these tests we usually check that a certain input leads to the expected output. They are used to test functionality. To run all tests use the command yarn test in the /webapp directory. Other useful commands are: yarn test -t test-name to run tests including test-name in their file or test names yarn test -o to run tests related to files that have been changed since the latest commit yarn test path/to/component.spec.js to run a single test file Documentation and manual testing Storybook is a great tool that performs two important functions in our project: Component documentation With Storybook our components can be documented in detail and offer a visual reference to other developers. When all components are properly documented, Storybook can be used as a big component library – where developers can browse through design tokens and components and immediately verify that the component offers the desired functionality. Manual testing in an isolated environment When adding new components or changing existing ones, Storybook can be helpful not only to document the feature for future use, but also to test different use cases (e.g. by passing different types of props) in an isolated playground. With the right addons, Storybook also gives immediate feedback on how well the component complies with accessibility guidelines. To run Storybook, first start the app, then enter the following command in a new terminal window: yarn storybook. The output should look similar to this: The ocelot.social Storybook will then be available on http://localhost:3002. "},"backend/testing.html":{"url":"backend/testing.html","title":"Backend tests","keywords":"","body":"Unit Testing "},"DOCKER_MORE_CLOSELY.html":{"url":"DOCKER_MORE_CLOSELY.html","title":"Docker More Closely","keywords":"","body":"Docker More Closely "},"CONTRIBUTING.html":{"url":"CONTRIBUTING.html","title":"Contributing","keywords":"","body":"CONTRIBUTING Thank you so much for thinking of contributing to the ocelot.social project! It's awesome you're here, we really appreciate it. :-) Getting Set Up Instructions for how to install all the necessary software and some code guidelines can be found in our main Readme or in our documentation. To get you started we recommend that you join forces with a regular contributor. Please join our Discord instance to chat with developers or just get in touch directly on an issue on either Github or Zenhub: We also can have pair programming sessions for you! We feel this is often the best way to get to know both the project and the team. Most developers are also available for spontaneous sessions. Development Flow We operate in two week sprints that are planned, estimated and prioritised on Zenhub. All issues are also linked to and synced with Github. Look for the good first issue label if you're not sure where to start! We try to discuss all questions directly related to a feature or bug in the respective issue, in order to preserve it for the future and for other developers. We use Discord for real-time communication. This is how we solve bugs and implement features, step by step: We find an issue we want to work on, usually during the sprint planning but as an open source contributor this can happen at any time. We communicate with the team to see if the issue is still available. (When you comment on an issue but don't get an answer there within 1-2 days try to mention @Ocelot-Social-Community/core-team to make sure we check in.) We make sure we understand the issue in detail – what problem is it solving and how should it be implemented? We assign ourselves to the issue and move it to In Progress on Zenhub. We start working on it in a new branch and open a pull request prefixed with [WIP] (work in progress) to which we regularly push our changes. When questions come up we clarify them with the team (directly in the issue on Github). When we are happy with our work and our PR is passing all tests we remove the [WIP] from the PR description and ask for reviews (if you're not sure who to ask there is @Ocelot-Social-Community/core-team which pings all core developers). We then incorporate the suggestions from the reviews into our work and once it has been approved it can be merged into master! Every pull request needs to: fix an issue (if there is something you want to work on but there is no issue for it, create one first and discuss it with the team) include tests for the code that is added or changed pass all tests (linter, backend, webapp, code coverage, end-to-end) be approved by at least 1 developer who is not the owner of the PR (when more than 10 files were changed it needs 2 approvals) Contribution Flow For Open Source Contributors See contributing in main README.md The Team There are many volunteers all around the world helping us build this network and without their contributions we wouldn't be where we are today. Big thank you to all of you! You can talk to our core team on Discord. And on Github you will mostly run into our core developers: Ulf (@ulfgebhardt) Moriz (@Mogge) Wolle (@Tirokk) Alex (@ogerly) Meetings and Pair Programming Sessions Times below refer to German Time – that's CET (GMT+1) in winter and CEST (GMT+2) in summer – because most ocelot.social Community core team members are living in Germany. Daily standup every Monday–Thursday 11:30 am (german time see above 👆🏼) in our Discord Office Cube all contributors welcome! everybody shares what they are working on and asks for help if they are blocked Philosophy We practice collective code ownership rather than strong code ownership, which means that: developers can make contributions to other people's PRs (after checking in with them) we avoid blocking because someone else isn't working, so we sometimes take over PRs from other developers everyone should always push their code to branches so others can see it We believe in open source contributions as a learning experience – everyone is welcome to join our team of volunteers and to contribute to the project, no matter their background or level of experience. To support your learning experience we founded the charity association busFaktor() e.V.. We use pair programming sessions as a tool for knowledge sharing. We can learn a lot from each other and only by sharing what we know and overcoming challenges together can we grow as a team and truly own this project collectively. As a volunteer you have no commitment except your own self development and your awesomeness by contributing to this free and open-source software project. Cheers to you! ` which indicate their respective financial compensation in Euros. You can bill us after your pull request got approved and merged into `master`. Payment methods are up to you: Bank transfer or PayPal is fine for us. Just send us your invoice as .pdf file attached to an E-Mail once you are done. Our Open-Source bounty program is a work-in-progress. Based on our future experience we will make changes and improvements. So keep an eye on this contribution guide. --> Programming Localization Quotation Marks The following characters are different from the programming quotation mark: \" or \\\" Please copy and paste the following quotes for the languages: de: „Dies ist ein Beispielsatz.“ en: “This is a sample sentence.” See https://grammar.collinsdictionary.com/easy-learning/when-do-you-use-quotation-marks-or-in-english Docker – More Closely Apple M1 Platform *Attention: For using Docker commands in Apple M1 environments!* Environment Variable For Apple M1 Platform If you encounter trouble building the docker containers on an Apple M1 chip you can try to explicitly define the target platform docker builds and pulls images for: # set env variable for your shell $ export DOCKER_DEFAULT_PLATFORM=linux/amd64 Or alternatively use a YAML docker compose overwrite file with platform: linux/amd64. Analyzing Docker Builds To analyze a Docker build, there is a wonderful tool called dive. Please sponsor if you're using it! The dive build command is exactly the right one to fulfill what we are looking for. We can use it just like the docker build command and get an analysis afterwards. So, in our main folder, we use it in the following way: # in main folder $ dive build --target -t \"ocelotsocialnetwork/:local-\" --build-arg BBUILD_DATE=\"\" --build-arg BBUILD_VERSION=\"\" --build-arg BBUILD_COMMIT=\"\" / The build arguments are optional. For the specific applications, we use them as follows. Backend Production For Backend # in main folder $ dive build --target production -t \"ocelotsocialnetwork/backend:local-production\" backend/ Development For Backend # in main folder $ dive build --target development -t \"ocelotsocialnetwork/backend:local-development\" backend/ Webapp Production For Webapp # in main folder $ dive build --target production -t \"ocelotsocialnetwork/webapp:local-production\" webapp/ Development For Webapp # in main folder $ dive build --target development -t \"ocelotsocialnetwork/webapp:local-development\" webapp/ "},"cypress/features.html":{"url":"cypress/features.html","title":"Feature Specification","keywords":"","body":"Network Specification ocelot.social is free and open-source social network code that connects information to action and promotes positive local and global change in all areas of life. Social: Interact with other people not just by commenting their posts, but by providing Pro & Contra arguments, give a Versus or ask them by integrated Chat or Let's Talk Knowledge: Read articles about interesting topics and find related posts in the More Info tab or by Filtering based on Categories and Tagging or by using the Fulltext Search. Action: Don't just read about how to make the world a better place, but come into Action by following provided suggestions on the Action tab provided by other people or Organisations. Features The following features will be implemented. This gets done in three steps: First we will implement a basic feature set and provide a test system to test the basic network functionality. In a second step we will make our prototype publicly available with an advanced feature set including the technology and organizational structure to drive a bigger public social network. In a third step all the remaining features will be implemented to build the full product. User Account Cucumber Features Sign-up Agree to Data Privacy Statement Agree to Terms of Service Login Logoff Change User Name Change Email Address Change Password Delete Account Download User's Content GDPR-Information about stored Content Choosing Interface Language (e.g. German / English / French) Persistent Links User Profile Cucumber Features Upload and Change Avatar Upload and Change Profile Picture Edit Social Media Accounts Edit Locale information Show and delete Bookmarks (later) Show Posts of a specific User Show Comments of a specific User Dashboard Clickdummy Show Link to own Profile Show Friends Widget Show Favorites Widget Show Get Friends Widget Show popular Hashtags Widget Show Mini-Statistics Widget (all time) Show Chatrooms Widget Show List of Let's Talk requests with online status of requesting people Posts Cucumber Features Creating Posts Persistent Links Upload Teaser Picture for Post Upload additional Pictures Editing Title and Content Allow embedded Conten (Videos, Sound, ...) Choosing a Category Adding Tags Choosing Language (e.g. German / English / French) Choosing Visibility (Public / Friends / Private) Shout Button for Posts Bookmark Posts (later) Optionally provide Let's Talk Feature Optionally provide Commenting Feature Comments Creating Comments Deleting Comments Editing Comments Upvote comments of others Notifications Cucumber features User @-mentionings Notify authors for comments Administrative notifications to all users Contribution List Show Posts by Tiles Show Posts as List Filter by Category (Health and Wellbeing, Global Peace & Non-Violence, ...) Filter by Mood (Funny, Happy, Surprised, Cry, Angry, ...) Filter by Source (Connections, Following, Individuals, Non-Profits, ...) Filter by Posts & Tools (Post, Events, CanDos, ...) Filter by Format Type (Text, Pictures, Video, ...) Extended Filter (Continent, Country, Language, ...) Sort Posts by Date Sort Posts by Shouts Sort Posts by most Comments Sort Posts by Emoji-Count (all Types) Blacklist Video Blacklist Users Blacklist specific Terms Blacklist Tags Switch on/off Adult Content Search Cucumber Features Search for Categories Search for Tags Fulltext Search CanDos Creating CanDos Editing Title and Content Choosing a Category Adding Tags Choosing Language (e.g. German / English / French) Choosing Visibility (Public / Friends / Private) Choosing Difficulty Editing Why - why should you do this Editing Usefulness - what is it good for Versus (interaction on existing Post) Create / edit / delete Versus Jobs Create, edit and delete Jobs by an User Handle Jobs as Part of Projects Handle Jobs done by Organizations Projects Create, edit and delete Projects Edit Title and Description for the Project Set Project Type Set and Edit Timeline for the Project Add Media to the Project Chat about the Project Pro & Contra Create Pro and Con (2-row) Add Arguments on Pro or Con Side Rate up Arguments Add Tags Attach Media Votes Create Votes (Surveys with two or more Choices) Add Title and Description Let Users vote Add Tags Bestlist Create Bestlist Create Votes (Surveys) Add Title and Description Add Tags Let Users vote for Best Item Set Settings (allow Uploads, allow Links, ...) Events Create Events Add Title and Description Choose Date and Location Add Tags More Info Shows automatically related information for existing post. Show related Posts Show Pros and Cons Show Bestlist Show Votes Link to corresponding Chatroom Take Action Shows automatically related actions for existing post. Show related Organisations Show related CanDos Show related Projects Show related Jobs Show related Events Show Map Badges System Importing Badge Information (CSV) Showing Badges Badge Administration by Admins Choosing Badges to display by User Chat Basic 1:1 Chat functionality Let's Talk Request Let's talk with Author of Post Requestor can request private or public Let's Talk Requestor can choose the Chat format (Video, Audio, Text) Interact with interested People 1:1 Approve request from Requestor Organizations Propose Organizations by users Set Name and Details Set Homepage Set Region Set Topic Commit organizations by HC-Org-Team Panel for Organisation Handling by themselfes Choose/Mark Users as authorized to manage an Organization Moderation Cucumber Features Report Button for users for doubtful Content Moderator Panel List of reported Content (later replaced by User-Moderation) Mark verified Users as Moderators Show Posts to be moderated highlighted to User-Moderators Statistics about kinds of reported Content by Time Statistics about Decisions in Moderation Administration Cucumber Features Provide Admin-Interface to send Users Invite Code Static Pages for Data Privacy Statement ... Create, edit and delete Announcements Pin a post to inform users Invitation Allow Users to invite others by Email Allow Users to register with Invite Code Double-opt-in by Email Internationalization Cucumber Features Frontend UI Backend Error Messages Federation Provide Server-Server ActivityPub-API Provide User-Server Activitypub-API Receiving public addressed Article and Note Objects Receiving Like and Follow Activities Receiving Undo and Delete Activities for Articles and Notes Serving Webfinger records and Actor Objects Serving Followers, Following and Outbox collections "},"CODE_OF_CONDUCT.html":{"url":"CODE_OF_CONDUCT.html","title":"Code of conduct","keywords":"","body":"Contributor Covenant Code of Conduct Our Pledge In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to making participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation. Our Standards Examples of behavior that contributes to creating a positive environment include: Using welcoming and inclusive language Being respectful of differing viewpoints and experiences Gracefully accepting constructive criticism Focusing on what is best for the community Showing empathy towards other community members Examples of unacceptable behavior by participants include: The use of sexualized language or imagery and unwelcome sexual attention or advances Trolling, insulting/derogatory comments, and personal or political attacks Public or private harassment Publishing others' private information, such as a physical or electronic address, without explicit permission Other conduct which could reasonably be considered inappropriate in a professional setting Our Responsibilities Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior. Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful. Scope This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers. Enforcement Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at devops@ocelot.social. The project team will review and investigate all complaints, and will respond in a way that it deems appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately. Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership. Attribution This Code of Conduct is adapted from the Contributor Covenant, version 1.4, available at http://contributor-covenant.org/version/1/4 "},"LICENSE.html":{"url":"LICENSE.html","title":"License","keywords":"","body":"LICENSE MIT License Copyright (c) 2018-2021 Ocelot.Social Community Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. "}}